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Introduction 



This manual describes the programming features of the UNIX system. It con- 
tains individual manual pages that describe commands, system calls, subrou- 
tines, file formats, and other useful topics, such as the ASCII table shown on 
ascii(5). It provides neither a general overview of the UNIX system nor details 
of the implementation of the system. 

Not all commands, features, and facilities described in this manual are available 
in every UNIX system. Some of the features require additional utilities that may 
not exist on your system. 

The manual is divided into five sections: 



1. Commands 

2. System Calls 

3. Subroutines: 

3C. C Programming Language Library Routines 

3S. Standard I/O Library Routines 

3E. Executable and Linking Format Library Routines 

3G. General Purpose Library Routines 

3M. Math Library Routines 

3X. Specialized Library Routines 

4. File Formats 

5. Miscellaneous Facilities 

Section 1 {Commands) describes commands that support C and other program- 
ming languages. 

Section 2 (System Calls) describes the access to the services provided by the 
UNIX system kernel, including the C language interface. 

Section 3 (Subroutines) describes the available general subroutines. In many 
cases, several related subroutines are described on the same manual page. Their 
binary versions reside in various system libraries. See intro(3) for descriptions 
of these libraries and the files in which they are stored. 

Section 4 (File Formats) documents the structure of particular kinds of files; for 
example, the format of the output of the link editor is given in a. out (4). 
Excluded are files used by only one command (for example, the assembler's 
intermediate files, if any). In general, the C language structures corresponding 
to these formats can be found in the directories /usr/include and 
/usr/include/sys. 
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Section 5 (Miscellaneous Facilities) contains a variety of things. Included are 
descriptions of character sets, macro packages, etc. 

References with numbers other than those above mean that the utility is con- 
tained in the appropriate section of another manual. References with (1) follow- 
ing the command mean that the utility is contained in this manual or the Use/s 
R^erence Manual In these cases, the SEE ALSO section of the entry in which the 
reference appears will point you to the correct book. 

Each section consists of a number of independent entries of a page or so each. 
Entries within each section are alphabetized, with the exception of the introduc- 
tory entry that begins each section. Some entries may describe several routines, 
commands, etc. In such cases, the entry appears only once, alphabetized under 
its "primary" name, the name that appears at the upper corners of each manual 
page. Subsections 3C and 3S are grouped together because their functions con- 
stitute the standard C library. 

All entries are based on a common format, not all of whose parts always 
appear: 

■ The NAME part gives the name(s) of the entry and briefly states its pur- 
pose. 

■ The SYNOPSIS part summarizes the use of the program or function being 
described. A few conventions are used, particularly in Section 2 (System 
Calls): 

□ Constant width typeface strings are literals and are to be typed 
just as they appear. 

□ Italic strings usually represent substitutable argument prototypes and 
program names found elsewhere in the manual. 

□ Square brackets [] around an argument prototype indicate that the 
argument is optional. When an argument prototype is given as name 
or file, it always refers to a file name. 

□ Ellipses . . . are used to show that the previous argument prototype 
may be repeated. 

□ A final convention is used by the commands themselves. An argu- 
ment beginning with a minus - or plus + sign is often taken to be 
some sort of flag argument, even if it appears in a position where a 
file name could appear. Therefore, it is unwise to have files whose 
names begin with - or + . 
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■ The DESCRIPTION part describes the utility. 

■ The EXAMPLE(S) part gives example(s) of usage, where appropriate. 

■ The FILES part gives the file names that are built into the program. 

■ The SEE ALSO part gives pointers to related information. 

■ The DIAGNOSTICS part discusses the diagnostic indications that may be 
produced. Messages that are intended to be self-explanatory are not 
listed. 

■ The NOTES part gives generally helpful hints about the use of the utility. 

A "Table of Contents'' and a "Permuted Index" derived from that table precede 
Section 1. The 'Termuted Index" is a list of keywords, given in the second of 
three columns, together with the context in which each keyword is found. Key- 
words are either topical keywords or the names of manual entries. Entries are 
identified with their section numbers shown in parentheses. This is important 
because there is considerable duplication of names among the sections, arising 
principally from commands and functions that exist only to exercise a particular 
system call. The right column lists the name of the manual page on which each 
keyword may be found. The left column contains useful information about the 
keyword. 
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1. Commands 



intro(l) introduction to programming commands 

admin(l) create and administer SCCS files 

ar(l) maintain portable archive or library 

as(l) assembler 

cb(l) C program beautifier 

cc(l) C compiler 

cdc(l) change the delta comment of an SCCS delta 

cflow(l) generate C flowgraph 

chrtbl(lM) generate character classification and conversion tables 

cof2elf (1) COFF to ELF object file translation 

colltbl(lM) create collation database 

comb(l) combine SCCS deltas 

convert (1) convert archive files to common formats 

cscope(l) interactively examine a C program 

ctrace(l) C program debugger 

cxref(l) generate C program cross-reference 

delta (1) make a delta (change) to an SCCS file 

dis(l) object code disassembler 

dump(l) dump selected parts of an object file 

get(l) get a version of an SCCS file 

help(l) ask for help with message numl)ers or SCCS commands 

install(lM) install commands 

ld(l) link editor for object files 

lex(l) generate programs for simple lexical tasks 

lint(l) a C program checker 

lorder(l) find ordering relation for an object library 

Iprof (1) display line-by-line execution count profile data 

m4(l) macro processor 

make(l) maintain, update, and regenerate groups of programs 

mcs(l) manipulate the comment section of an object file 

montbl(lM) create monetary database 

nm(l) print name list of an object file 

prof(l) display profile data 

prs(l) print an SCCS file 

regcmp(l) regular expression compile 

rmdel(l) remove a delta from an SCCS file 

sact(l) ; print current SCCS file editing activity 

sccsdiff(l) compare two versions of an SCCS file 
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sdb(l) symbolic debugger 

sized) print section sizes in bytes of object files 

strip (1) strip sjmibol table, debugging and line number information from an object file 

tsort(l) topological sort 

unget(l) undo a previous get of an SCCS file 

val(l) validate an SCCS file 

vc(l) version control 

what(l) print identification strings 

yacc(l) yet another compiler-compiler 

2. System Calls 

intro(2) introduction to system calls and error numbers 

access (2) determine accessibility of a file 

acct(2) enable or disable process accounting 

alarm (2) set a process alarm clock 

brk, sbrk(2) change data segment space allocation 

chdir(2) change working directory 

chmod(2) change mode of file 

chown(2) change owner and group of a file 

chroot(2) change root directory 

close (2) close a file descriptor 

creat(2) create a new file or rewrite an existing one 

dup(2) duplicate an open file descriptor 

exec: execl, execv/ execle, execve, execlp, execvp(2) execute a file 

exit, exit (2) terminate process 

fcntl(2) file control 

fork(2) create a new process 

getdents(2) read directory entries and put in a file system independent format 

getmsg(2) get next message off a stream 

getpid, getpgrp, getppid(2) get process, process group, and parent process IDs 

getuid, geteuid, getgid, getegid(2) 

get real user, effective user, real group, and effective group IDs 

ioctl(2) control device 

kill (2) send a signal to a process or a group of processes 

link(2) link to a file 

lseek(2) move read/write file pointer 

mkdir(2) make a directory 

mknod(2) make a directory, or a special or ordinary file 

moimt(2) mount a file system 
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msgctl(2) message control operations 

msgget(2) get message queue 

msgop(2) message operations 

nice (2) change priority of a process 

open (2) open for reading or writing 

pause (2) suspend process until signal 

pipe (2) create an interprocess channel 

plock(2) lock process, text, or data in memory 

poIl(2) STREAMS input/output multiplexing 

profil(2) execution time profile 

ptrace(2) process trace 

putmsg(2) send a message on a stream 

read (2) read from file 

rmdir(2) remove a directory 

semctl(2) semaphore control operations 

semget(2) get set of semaphores 

semop(2) semaphore operations 

setpgrp(2) set process group ID 

setuid, setgid(2) set user and group IDs 

shmctl(2) shared memory control operations 

shmget(2) get shared memory segment identifier 

shmop(2) shared memory operations 

signal (2) specify what to do upon receipt of a signal 

sigset, sighold, sigrelse, sigignore, sigpause(2) signal management 

Stat, f Stat (2) get file status 

statfs, fstatfs(2) get file system information 

stime(2) set time 

sync (2) update super block 

sysfs(2) get file system type information 

time (2) get time 

times (2) get process and child process times 

uadmin(2) administrative control 

ulimit(2) get and set user limits 

umask(2) set and get file creation mask 

umount(2) immount a file system 

uname(2) get name of current UNIX system 

unlink(2) remove directory entry 

ustat(2) get file system statistics 

utime(2) set file access and modification times 

wait (2) , wait for child process to stop or terminate 
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write (2) write on a file 

3. Functions 

introO) introduction to functions and libraries 

a641, 164a (3C) convert between long integer and base-64 ASCII string 

abort (3C) generate an abnormal termination signal 

abs, labsOO return integer absolute value 

addseverity (3C) build a list of severity levels for an application for use with fmtmsg 

atexit(3C) add program termination routine 

bsearch(3C) binary search a sorted table 

clock (3C) report CPU time used 

conv: toupper, tolower, _toupper, _tolower, toascii(3C) translate characters 

crj^t, setkey, encrypt (3C) generate encryption 

ctermid(3S) generate file name for terminal 

ctime, localtime, gmtime, asctime, tzset(3C) convert date and time to string 

ctype: isdigit, isxdigit, islower, isupper, isalpha, isalnum, isspace, iscntrl, ispunct, 

isprint, isgraph, isascii(3C) character handling 

cuserid(3S) get character login name of the user 

dial(3C) establish an out-going terminal line connection 

difftime(3C) computes the difference between two calendar times 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir(3C) directory operations 

div, ldiv(3C) compute the quotient and remainder 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, 

lcong48(3C) generate uniformly distributed pseudo-random numbers 

dup2(3C) duplicate an open file descriptor 

ecvt^ fcvt, gcvt(3C) convert floating-point number to string 

end, etext, edata(3C) last locations in program 

fclose, fflush(3S) close or flush a stream 

ferror, feof, clearerr, fileno(3S) stream status inquiries 

ffs(3C) find first set bit 

fmtmsg(3C) display a message on stderr or system console 

fbpen, f reopen, fdopen(3S) open a stream 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky(3C) 

IEEE floating-point environment control 

fread, fwrite(3S) binary input/output 

frexp, Idexp, logb, modf, modff, nextafter, scalb(3C) 

manipulate parts of floating-point numbers 

fseek, rewind, ftell(3S) reposition a file pointer in a stream 

fsetpos, fgetpos(3C) reposition a file pointer in a stream 
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ftw(3C) walk a file tree 

getc, getchar, fgetc, getw(3S) get character or word from a stream 

getcwd(3C) get pathname of current working directory 

getenv(3C) return value for environment name 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent(3C) get group file entry 

getlogin(3C) get login name 

getmntent, getmntany(3C) get mnttab file entry 

getopt(3C) get option letter from argument vector 

get;pass(3C) read a password 

getpw(3C) get name from UID 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent(3C) 

manipulate password file entry 

gets, fgets(3S) get a string from a stream 

getsubopt(3C) parse suboptions from a string 

getut: getutent, getutid, getutline, pututline, setutent, endutent, utmpname(3C) 

access utmp file entry 

hsearch, hcreate, hdestroy (3C) manage hash search tables 

insque, remque(3C) insert /remove element from a queue 

isnan, isnand, isnanf, finite, fpclass, unordered (3C) 

determine type of floating-point number 

13tol, ltol3(3C) convert between 3-byte integers and long integers 

localeconv(3C) get numeric formatting information 

lockf (3C) record locking on files 

Isearch, lfind(3C) linear search and update 

malloc, free, realloc, calloc(3C) memory allocator 

mbchar: mbtowc, mblen, wctomb(3C) multibyte character handling 

nibstring: mbstowcs, wcstombs(3C) multibyte string functions 

memory: memccpy, memchr, memcmp, memcpy, memmove, memset(3C) 

, memory operations 

mkfifo(3C) create a new FIFO 

mktemp(3C) , make a unique file name 

mktime(3C) converts a tm structure to a calendar time 

monitor (3C) prepare execution profile 

offsetof(3C) offset of structure member 

perror(3C) print system error inessages 

popen, pclose(3S) , initiate pipe to/from a proce^i 

printf, fprintf, sprintf(3S) print formatted output 

putc, putchar, fputc, putw(3S) put character or word on a stream 

putenv(3C) change or add value to environment 

putpwent(3C) , write password file entry 
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puts, fputs(3S) put a string on a stream 

qsort(3C) quicker sort 

raise (3C) send signal to program 

rand, srandOO simple random-number generator 

remove(3C) remove file 

rename (3C) rename file 

scanf, fscanf, sscanf(3S) convert formatted input 

setbuf, setvbuf (3S) assign buffering to a stream 

setjmp, longjmp(3C) non-local goto 

setlocale(3C) modify and query a program's locale 

sleep (3C) suspend execution for interval 

ssignal, gsignal(3C) software signals 

stdio(3S) standard buffered input/output package 

stdipc: ftok(3C) standard interprocess communication package 

strcoll(30 string collation 

strerror(3C) get error message string 

strftime, cftime, ascftime,(3C) , convert date and time to string 

string: strcat, strdup, stmcat, strcmp, strncmp, strcpy, stmcpy, strlen, strchr, 

strrchr, strpbrk, strspn, strcspn, strtok, strstr(3C) string operations 

strtod, atof,(3C) convert string to double-precision number 

strtol, strtoul, atol, atoi(3C) convert string to integer 

strxfrm(3C) string transformation 

swab(3C) swap bytes 

system(3S) issue a shell command 

tmpfile(3S) create a temporary file 

tmpnam, tempnam(3S) create a name for a temporary file 

tsearch, tfind, tdelete, twalk(3C) manage binary search trees 

ttyname, isatty(3C) find name of a terminal 

ttyslot(3C) find the slot in the utmp file of the current user 

ungetc(3S) push character back onto input stream 

vprintf, vfprintf, vsprintf(3S) print formatted output of a variable argument list 

elf(3E) object file access library 

elf_begin(3E) make a file descriptor 

elf_cntl(3E) control a file descriptor 

elf_end(3E) finish using an object file 

elf errmsg, elf_errno(3E) error handling 

elf_fill(3E) set fill byte 

elf^flagdata, elf flagehdr, elf^flagelf, elf_flagphdr, elf_flagscn, elf_flagshdr(3E) 

* manipulate flags 

elf_fsize: elf 32_f size (3E) return the size of an object file type 
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elf_getarhdr(3E) retrieve archive member header 

elf_getarsym(3E) retrieve archive symbol table 

elf_getbase(3E) get the base offset for an object file 

elf_getdata, elf newdata, elf_rawdata(3E) get section data 

elf_getehdr: elf32_^etehdr, elf32_newehdr(3E) retrieve class-dependent object file header 

elf_getident(3E) retrieve file identification data 

elf_getphdr: elf32_getphdr, elf32_newphdr(3E) 

retrieve class-dependent program header table 

elf_getscn, elf ndxscn, elf newscn, elf_nextscn(3E) get section information 

elf getshdr: elf32_^etshdr(3E) retrieve class-dependent section header 

elf_hash(3E) compute hash value 

elf_kind(3E) determine file type 

elf_next(3E) sequential archive member access 

elf_rand(3E) random archive member access 

elf_rawfile(3E) retrieve uninterpreted file contents 

elf_strptr(3E) make a string pointer 

elf_update(3E) update an descriptor 

elf_version(3E) coordinate library and application versions 

elf_xlate: elf32_xlatetof, elf32_xlatetom(3E) class-dependent data translation 

nlist(3E) get entries from name list 

basename(3G) return the last element of a path name 

bgets(3G) read stream up to next delimiter 

bufsplit(3G) split buffer into fields 

copylist(3G) copy a file into memory 

dirname(3G) report the parent directory name of a file path name 

gmatch(3G) shell global pattern matching 

isencrypt(3G) determine whether a character buffer is encrypted 

mkdirp, rmdirp(3G) create, remove directories in a path 

p2open, p2close(3G) open, close pipes to and from a command 

pathfind(3G) search for named file in named directories 

regcmp, regex(3G) compile and execute regular expression 

regexpr: compile, step, advance(3G) regular expression compile and match routines 

str: strfind, strrspn, strtrns(3G) string manipulations 

strccpy: streadd, strcadd, strecpy(3G) .. copy strings, compressing or expanding escape codes 

intro(3M) introduction to the math library 

bessel: jO, jl, jn, yO, yl, yn(3M) Bessel functions 

erf, erfc(3M) error function and complementary error function 

exp, expf, cbrt, log, logf, loglO, loglOf, pow, powf, sqrt, sqrtf(3M) 

exponential, logarithm, power, square root functions 
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floor, floorf, ceil, ceilf, copysign, fmod, fmodf, fabs, fabsf, rint, remainder (3M) 

floor, ceiling, remainder, absolute value functions 

gamma, IgammaOM) log gamma function 

hypotOM) Euclidean distance function 

matherr(3M) error-handling function 

sinh, sinhf, cosh, CQshf, tanh, tanhf, asinh, acosh, atanh(3M) hyperbolic functions 

trig: sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, acosf, atan, atanf, atanl, 

atan2f(3M) trigonometric functions 

assert (3X) verify program assertion 

crypt(3X) , password and file encryption functions 

libwindows(3X) windowing temiin^l function library 

maillock(3X) manage lockfile for user's mailbox 

malloc, free, realloc, calloc, mallopt, mallinfo(3X) memory allocator 

sputl, sgetl(3X) access long integer data in a machine-independent fashion 



4. File Formats 



intro(4) introduction to file formats 

a.out(4) ELF (Executable and Linking Format) files 

ar(4) , , archive file format 

core(4) , core image file 

limits (4) header file for implementation'-specifiG cpnst^iits 

sccsfile(4) , format of SCCS file 

strftime(4) , language specific strings 

timezone(4) , set default system time zone 

utmp, wtmp(4) utmp and wtmp entry formats 



5. Miscellaneous Facilities 



intro(5) , introduction to miscellany 

ascii(5) map of ASCII character set 

environ (5) user environment 

fcntl(5) , file control options 

jagent(5) , host control of windowing terminal 

layers (5) , protocol used between host and windowing terminal under layers(l) 

math (5) math functions and constants 

prof(5) , , profile within a function 

regexp: compile, step, advance (5) regular expression compile and match routines 

stat(5) , data returned by stat system call 

stdarg(5) handle variable argument list 
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types (5) primitive system data types 

values(5) machine-dependent values 

varargs(5) handle variable argument list 

xtproto(5) multiplexed channels protocol used by xt driver 
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13tol, ltol3 convert between 3-byte integers and long integers 13tol(3Q 

integer and base-64 ASCII string a641, 164a convert between long a641(3Q 

abort generate an abnormal termination signal abort(3C) 

termination signal abort generate an abnormal abort(3C) 

value abs, labs return integer absolute , ^bs(3Q 

abs, labs return integer absolute value abs(3Q 

floor, ceiling, remainder, absolute value functions /remainder , floor(3M) 

utime 3et file access and modification times utime(2) 

file access determine accessibility of a access(2) 

elf_next sequential archive member access , elf_next(3E) 

elf_rand random archive member access , elf_rand(3E) 

elf object file access library , elf(3E) 

machine-independent/ sputl, sgetl access lon^ integer data in a sputl(3X) 

setutent, endutent, utmpname access utmp file entry /pututline, getut(3Q 

access determine accessibility of a file access(2) 

acct enable or disable process accounting acct(2) 

accovmting acct enable or disable process , acct(2) 

/cos, cosf, tan, tanf, asin, asinf, acos, acosf, atan, atanf, atan2,/ big(3M) 

/cost tan, tant asin, asinf, acos, acosf, atan, atanf, atan2, atan2f/ trig(3M) 

/coshf, tanh, tanhf, asinh, acosh, atanh hyperbolic functions .„.,.,. sinh(3M) 

print current SCCS file editing activity sact sact(l) 

atexit add program termination routine atexit(3Q 

putenv change or add v^lue to environment , putenv(3C) 

severity levels for an application/ addseverity build a list of addseverity(3Q 

files admin create and administer SCCS , admin(l) 

admin create and administer SCCS files .„. .„, admin(l) 

uadmin administrative control ua4min(2) 

and match/ regexp: compile, step, advance regular expression compile regexp(5) 

and match/ regexpr: compile, step, advance regular expression compile « rege)q?r(3G) 

alarm set a process alarm clock alarm(2) 

alarm set a process alarm dock alarm(2) 

brk, sbrk change data segment space allocation , , brk(2) 

free, realloc, calloc memory allocator malloc, „.„... malloc(3C) 

calloc, mallopt, mallinfo memory allocator malloc, free, realloc, maUoc(3X) 

Format) files a.out ELF (Executable and Linking a.out(4) 

/a list of severity levels for an application for use with fintmsg addseverity(3Q 

elf_version coordinate library and application versions elf_version(3E) 

ar archive file format , ar(4) 

library ar maintain portable archive or , , ar(l) 

ar ardtive file format ar(4) 

convert convert archive files to common formats convert(l) 

elfjiext sequential ardiive member access elf_next(3E) 

elf jrand random archive member access ....„.,, elf_rand(3E) 

elf ^etarhdr retrieve archive member header , elf getarhdr(3E) 

ar maintain portable archive or library ar(l) 

elf^etarsym retrieve archive symbol table „ , elf^getarsymOE) 

stdarg handle variable argument list stdarg(5) 
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varargs handle variable argument list varargs(5) 

formatted output of a variable argument list /vsprintf print vprintf(3S) 

getopt get option letter from argviment vector getopt(3C) 

string strftime, cftime, ascftime, convert date and time to strftime(3C) 

asdi map of ASCII character set asdi(5) — 

asdi map of ASCII character set ascii(5) 

between long integer and base-64 ASCII string a641, 164a convert a641(3Q 

time to/ ctime, localtime, gmtime, asctime, tzset convert date and ctime(3C) 

/sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, acosf, atan,/ trig(3M) 

/sinf, cos, cosf, tan, tanf, asin, asinf, acos, acosf, atan, atanf,/ trig(3M) 

/cosh, coshf, tanh, tanhf, asinh, acosh, atanh hyperbolic/ sinh(3M) 

or sees commands help ask for help with message nimibers help(l) 

as assembler as(l) 

assert verify program assertion assert(3X) 

assert verify program assertion assert(3X) 

setbuf, setvbuf assign buffering to a stream setbuf(3S) 

tanf, asin, asinf, acos, acosf, atan, atanf, atan2, atan2f/ /tan, trig(3M) 

asinf, acos, acosf, atan, atanf, atan2, atan2f trigonometric/ /asin, trig(3M) 

/acos, acosf, atan, atanf, atan2, atan2f trigonometric functions trig(3M) 

/asin, asinf, acos, acosf, atan, atanf, atan2, atan2f trigonometric/ trig(3M) 

tanh, tanhf, asinh, acosh, atanh hyperbolic functions /coshf, sinh(3M) 

routine atexit add program termination atexit(30 

double-precision ntimber strtod, atof, convert string to strtod(3Q 

strtol, strtoul, atol, atoi convert string to integer strtol(3C) 

integer strtol, strtoul, atol, atoi convert string to strtol(3C) 

elf _getbase get the base offset for an object file elf_getbase(3E) 

convert between long integer and base-64 ASCII string a641, 164a a641(3Q 

a path name basename return the last element of basename(3G) 

cb C program beautifier cb(l) 

bessel: jO, jl, jn, yO, yl, yn Bessel functions bessel(3M) 

Bessel functions bessel: jO, jl, jn, yO, yl, yn bessel(3M) 

delimiter bgets read stream up to next bgets(3G) 

fread, fwrite binary input/ output fread(3S) 

bsearch binary search a sorted table bsearch(3C) 

tfind, tdelete, twalk manage binary search trees tsearch, tsearch(30 

ffs find first set bit ffs(3C) 

sync update super block sync(2) 

allocation brk, sbrk change data segment space .-. brk(2) 

table bsearch binary search a sorted bsearch(3C) 

bufsplit split buffer into fields bufsplit(3G) 

determine whether a character buffer is encrypted isencrypt isencrypt(3G) 

stdio standard buffered input/output padcage stdio(3S) 

setbuf, setvbuf assign btiffering to a stream setbuf (3S) 

bufsplit split buffer into fields bufsplit(3G) 

an application for use/ addseverity build a list of severity levels for addseverity(3C) 

elf__fill set fill byte elf__fill(3E) 

size print section sizes in bytes of object files size(l) 
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swab swap bytes swab(3C) 

cx: C compiler cc(l) 

cflow generate C flowgraph cflow(l) 

cb C program beautifier cb(l) 

lint a C program checker lint(l) 

cxref generate C program cross-reference cxref(l) 

cscope interactively examine a C program cscope(l) 

ctrace C program debugger ctrace(l) 

mktime converts a tm structure to a calendar time mktime(3C) 

computes the difference between two calendar times difftime diff time(3Q 

Stat data returned by stat system call stat(5) 

allocator malloc, free, realloc, calloc, mallopt, mallinfo memory malloc(3X) 

malloc, free, realloc, calloc memory allocator malloc(3C) 

intro introduction to system calls and error numbers intro(2) 

cb C program beautifier cb(l) 

pow, powf, sqrt, sqrtf/ exp, expf, cbrt, log, logf, loglO, loglOf, exp(3M) 

cc C compiler cc(l) 

sees delta cdc change the delta comment of an cdc(l) 

fabs, fabsf, rint,/ floor, floorf, ceil, ceilf, copy sign, fmod, fmodf, floor(3M) 

fabsf, rint,/ floor, floorf, ceil, ceilf, copysign, fmod, fmodf, fabs, floor(3M) 

/fabs, fabsf, rint, remainder floor, ceiling, remainder, absolute value/ floor(3M) 

cflow generate C flowgraph cflow(l) 

time to string strftime, cftime, ascftime, convert date and strftime(3C) 

allocation brk, sbrk change data segment space brk(2) 

chmod change mode of file chmod(2) 

putenv change or add value to environment putenv(3C) 

chown change owner and group of a file chown(2) 

nice change priority of a process nice(2) 

chroot change root directory chroot(2) 

delta cdc change the delta comment of an SCCS cdc(l) 

delta make a delta (change) to an SCCS file delta(l) 

chdir change working directory chdir(2) 

pipe create an interprocess channel pipe(2) 

xtproto multiplexed channels protocol used by xt driver xtproto(5) 

ungetc push character back onto input stream imgetc(3S) 

isencrypt determine whether a character buffer is encrypted isencrypt(3G) 

conversion tables chrtbl generate character classification and chrtbl(lM) 

ispunct, isprint, isgraph, isascii character handling /iscntrl, ctype(3Q 

mbtowc, mblen, wctomb multibyte character handling mbchar: mbchar(3C) 

cuserid get character login name of the user cuserid(3S) 

getc, getchar, fgetc, getw get character or word from a stream getc(3S) 

putc, putchar, fputc, putw put character or word on a stream putc(3S) 

asdi map of ASQI character set ascii(5) 

tolower, toasdi translate characters /tolower, toupper, conv(3C) 

chdir change working directory chdir(2) 

lint a C program checker lint(l) 

times get process and child process times times(2) 
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wait wait for child process to stop or terminate wait(2) 

chmod change mode of file chmod(2) 

file chown change owner and group of a chown(2) 

chroot change root directory chroot(2) 

classification and conversion/ chrtbl generate character chrtbl(lM) 

/el£32jdatetof, elf32_xlatetom dass-dependent data translation elf jdate(3E) 

/elf32_newehdr retrieve dass-dependent object file header elf_getehdr(3E) 

table /el£32_newphdr retrieve dass-dependent program header elf ^etphdr(3E) 

elf_getshdr: elf32_getshdr retrieve dass-dependent section header elf_getshdr(3E) 

tables chrtbl generate character dassification and conversion chrtbl(lM) 

inquiries ferror, feof, dearerr, fileno stream status ferror(3S) 

alarm set a process alarm dock alarm(2) 

dock report CPU time used dock(30 

dose dose a file descriptor dose(2) 

dose dose a file descriptor dose(2) 

fdose, ffiush dose or flush a stream fdose(3S) 

p2open, p2dose open, dose pipes to and from a command p2open(3G) 

/telldir, seekdir, rewinddir, dosedir directory operations directory(3C) 

dis object code disassembler dis(l) 

compressing or expanding escape codes /strecpy copy strings, strccpy(3G) 

translation cof2elf COFF to ELF object file cof2df(l) 

cof2elf COFF to ELF object file translation cof2elf(l) 

colltbl create collation database colltbl(lM) 

strcoll string collation strcoll(3Q 

colltbl create collation database colltbl(lM) 

comb combine SCCS deltas comb(l) 

comb combine sees deltas comb(l) 

open, dose pipes to and from a command p2open, p2dose p2open(3G) 

system issue a shell command system(3S) 

help with message ntimbers or SCCS commands help ask for help(l) 

install install commands install(lM) 

intro introduction to programming conunands intro(l) 

cdc diange the delta comment of an SCCS delta cdc(l) 

mcs manipulate the comment section of an object file mcs(l) 

convert convert archive files to common formats convert(l) 

stdipc: f tok standard interprocess oonmiunication package stdipc(30 

file sccsdiff compare two versions of an SCCS sccsdiff(l) 

expression regcmp, regex compile and execute regular regcmp(3G) 

/step, advance regular expression compile and match routines regexp(5) 

/step, advance regular expression compile and matdi routines regexpr(3G) 

regcmp regular expression compile regcmp(l) 

expression compile and/ regexp: compile, step, advance regular regexp(5) 

expression compile and/ regexpr: compile, step, advance regular regexpr(3G) 

ccC compiler cc(l) 

yacc yet another compiler-compiler yacc(l) 

erf, erfc error function and complementary error function erf(3M) 

/strcadd, strecpy copy strings, compressing or expanding escape/ strccpy(3G) 
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elf_hash compute hash value elf_hash(3E) 

div, Idiv compute the quotient and remainder div(3Q 

calendar times difftime computes the difference between two difftime(3Q 

an out-going terminal line connection dial establish dial(3Q 

a message on stderr or system console fmtmsg display fmtmsg(3Q 

file for implementation-spedfic constants limits header limits(4) 

math math functions and constants math(5) 

retrieve uninterpreted file contents elf rawfile elf rawfile(3E) 

elf cntl control a file descriptor elf_cntl(3E) 

ioctl control device ioctl(2) 

fend file control fcntl(2) 

IEEE floating-point environment control /fpgetsticky, fpsetsticky fpgetrotmd(3Q 

jagent host control of windowing terminal jagent(5) 

msgctl message control operations msgctl(2) 

semctl semaphore control operations semctl(2) 

shmctl shared memory control operations shmctl(2) 

fcntl file control options fcntl(5) 

uadmin administrative control uadmin(2) 

vc version control vc(l) 

tolower, toasdi translate/ conv: toupper, tolower, toupper, conv(3C) 

character classification and conversion tables chrtbl generate chrtbl(lM) 

formats convert convert archive files to common convert(l) 

long integers 13tol, ltol3 convert between 3-byte integers and 13tol(30 

base-64 ASQI string a641, 164a convert between long integer and a641(3Q 

common formats convert convert archive files to convert(l) 

/localtime, gmtime, asctime, tzset convert date and time to string ctime(3C) 

strftime, cftrme, ascftime, convert date and time to string strftime(3C) 

string ecvt, fcvt, gcvt convert floating-point nimiber to ecvt(3Q 

scanf, fscanf, sscanf convert formatted input scanf(3S) 

number strtod, atof, convert string to double-precision strtod(3C) 

strtol, strtoul, atol, atoi convert string to integer strtol(3C) 

calendar time mktime converts a tm structure to a mktime(3C) 

versions elf_version coordinate library and application elf_version(3E) 

copylist copy a file into memory copylist(3G) 

strccpy: streadd, strcadd, strecpy copy strings, compressing or/ strccpy(3G) 

copylist copy a file into memory copylist(3G) 

Tint,/ floor, floorf, ceil, ceilf, copysign, ftnod, fmodf, fabs, fabsf, floor(3M) 

core core image file core(4) 

core core image file core(4) 

acos, acosf,/ trig: sin, sinf, cos, cosf, tan, tanf, asin, asinf, trig(3M) 

acosf, atan,/ trig: sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, trig(3M) 

asinh, acosh,/ sinh, sinhf, cosh, coshf, tanh, tanhf, sinh(3M) 

acosh,/ sinh, sinhf, cosh, coshf, tanh, tanhf, asinh, sinh(3M) 

display line-by-line execution coimt profile data Iprof lprof(l) 

dock report CPU time used clock(3Q 

an existing one creat create a new file or rewrite creat(2) 

tmpnam, tempnam create a name for a temporary file tmpnam(3S) 
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mkfifo create a new FIFO mkfifo(3C) 

existing one creat create a new file or rewrite an creat(2) 

fork create a new process fork(2) 

tmpfUe CTeate a temporary file tmpfile(3S) 

pipe create an interprocess channel pipe(2) 

adnun create and admiiuster SCCS files admin(l) 

colltbl create collation database colltbl(lM) 

montbl create monetary database montbl(lM) 

path mkdirp, rmdirp create, remove directories in a mkdirp(3G) 

vimask set and get file creation mask imiask(2) 

cxref generate C program cross-reference cxref (1) 

functions aypt password and file encryption crypt(3X) 

encryption crypt, setkey, encrypt generate crypt(3C) 

program cscope interactively examine a C cscope(l) 

terminal ctermid generate file name for ctermid(3S) 

tzset convert date and time to/ ctime, localtime, gmtime, asctime, ctime(3C) 

ctrace C program debugger ctrace(l) 

isupper, isalpha, isalnum,/ ctype: isdigit, isxdigit, islower, ctype(30 

sact print current SCCS file editing activity sact(l) 

uname get name of current UNIX system uname(2) 

the slot in the utmp file of the current user ttyslot find ttyslot(3C) 

getcwd get pathname of current working directory getcwd(3Q 

the user cuserid get character login name of cuserid(3S) 

cross-reference cxref generate C program cxref(l) 

elf_rawdata get section data elf_getdata, elf_newdata, elf_getdata(3E) 

retrieve file identification data elf_getident elf getident(3E) 

sputl, sgetl access long integer data in a machine-independent/ sputl(3X) 

plock lock process, text, or data in memory plock(2) 

execution count profile data Iprof display line-by-line Iprof (1) 

prof display profile data prof(l) 

Stat data returned by stat system call stat(5) 

brk, sbrk change data segment space allocation brk(2) 

elf32_xlatetom class-dependent data translation /elf32__xlatetof, elf_xlate(3E) 

types primitive system data types types(5) 

colltbl create collation database colltbl(lM) 

montbl create monetary database montbl(lM) 

gmhme, asctime, tzset convert date and time to string /localtime, ctime(3C) 

strftime, cftime, ascftime, convert date and time to string strftime(3C) 

ctrace C program debugger ctrace(l) 

sdb symbolic debugger sdb(l) 

strip strip symbol table, debugging and line nimiber/ strip(l) 

timezone set default system time zone timezone(4) 

bgets read stream up to next delimiter bgets(3G) 

change the delta comment of an SCCS delta cdc cdc(l) 

delta make a delta (change) to an SCCS file delta(l) 

cdc change the delta comment of an SCCS delta cdc(l) 

rmdel remove a delta from an SCCS file rmdel(l) 
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sees file delta make a delta (change) to an delta(l) 

comb combine sees deltas comb(l) 

close dose a file descriptor close(2) 

dup duplicate an open file descriptor dup(2) 

dup2 duplicate an open file descriptor dup2(3Q 

elf begin make a file descriptor elf_begin(3E) 

elf cntl control a file descriptor elf_cntl(3E) 

elf^update update an descriptor elf_update(3E) 

access determine accessibility of a file access(2) 

elf kind determine file type elf_kind(3E) 

/isnanf, finite, fpclass, unordered determine type of floating-point/ isnan(3C) 

buffer is encrypted isencrypt determine whether a character isencrypt(3G) 

ioctl control device ioctl(2) 

terminal line connection dial establish an out-going dial(3Q 

times diff time computes the difference between two calendar difftime(3Q 

between two calendar times difftime computes the difference difftime(3Q 

mkdirp, rmdirp create, remove directories in a path mkdirp(3G) 

search for named file in named directories pathfind pathfind(3G) 

chdir change working directory chdir(2) 

chroot change root directory chroot(2) 

system independent/ getdents read directory entries and put in a file getdents(2) 

unlink remove directory entry unlink(2) 

get pathname of current working directory getcwd getcwd(3C) 

mkdir make a directory mkdir(2) 

dimame report the parent directory name of a file path name dimame(3G) 

telldir, seekdir, rewinddir,/ directory: opendir, readdir, directory(3C) 

seekdir, rewinddir, closedir directory operations /telldir, directory (3C) 

file mknod make a directory, or a special or ordinary mknod(2) 

rmdir remove a directory rmdir(2) 

name of a file path name dimame report the parent directory dimame(3G) 

dis object code disassembler dis(l) 

acct enable or disable process accounting acct(2) 

dis object code disassembler dis(l) 

system console fmtmsg display a message on stderr or fmtmsg(3C) 

count profile data Iprof display line-by-line execution Iprof(l) 

prof display profile data prof(l) 

hypot Euclidean distance function hypot(3M) 

/seed48, lcong48 generate uniformly distributed pseudo-random numbers drand48(3Q 

remainder div, Idiv compute the quotient and div(3Q 

strtod, atof, convert string to double-precision number strtod(3C) 

mrand48, jrand48, srand48, seed48,/ drand48, erand48, lrand48, nrand48, drand48(3Q 

channels protocol used by xt driver xtproto multiplexed xtproto(5) 

object jfile dump dvimp selected parts of an dvimp(l) 

file dimtp dump selected parts of an object dump(l) 

descriptor dup duplicate an op>en file dup(2) 

descriptor dup2 duplicate an open file dup2(3Q 

dup duplicate an open fQe descriptor dup(2) 
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dup2 duplicate an open file descriptor * » dup2(3Q 

floating-point number to string ecvt, fcvt, gcvt convert * * ecvt(3C) 

end^etext edata last locations in program end(3Q 

sact print current SCCB ^e editing activity sact(l) 

Id liftk editor for object files ld(l) 

effective user^ real group, and effective group IDs /get real user, gettiid(2) 

/getgid, getegid get real user, effective user, real group, and/ getuid(2) 

insque, remque insert/remove element from a queue insque(3C) 

basename return the last element of a path name basename(3G) 

files a.out ELF (Executable and Linking Format) a.out(4) 

elf object file access library elf(3E) 

cof2elf COFF to ELF object fQe translation cof2elf(l) 

object file type elf__fsize: elf32_fsize return the size of an elf_fsize(3E) 

retrieve/ elf^etehdr: elf32 _jetehdr, elf32jiewehdr elf_geTehdr(3E) 

rettieve/ elf_jetphdr: elf32^etphdr, elf32_newphdr elf_getphdr(3E) 

dass-dependent/ elf^getshdr: elf32_^tshdr retrieve elf^etshdr(3E) 

elf getehdr: eif32^etehdr, elf32_newehdr retrieve/ elf_getehdr(3E) 

elf_getphdr: elf32_getphdr, elf32_newphdr retrieve/ elf_getphdr(3E) 

dass-dependent data/ elf^^xlate: elf32_xlatetof, elf32_xlatetom , elf_xlate(3E) 

^__xlate: el£32_)datetofc elf32_xlatetom dass-dependent data/ elf xlate(3E) 

elf_begin make a file descriptor elf_begin(3E) 

elf_^cntl control a file descriptor elf cntl(3E) 

elf^end finish using an object file elf_end(3E) 

handling elf errmsg, elfjerrno error elf_errmsg(3E) 

elf^eitmsg, elf errno error h^dling elf errmsg(3E) 

elfjSil set fill byte ^ elfjm(3E) 

elf^^flagelf, elf^^flagphdr,/ elf flagdata, elf__flagehdr, elf_flagdata(3E) 

elf flagphdr,/ elf_^flagdata, elf flagehdr, elf_^flagelf, elf flagdata(3E) 

elf_flagdata, elf_^flagehdr, elf fiagelf, elf flagphdr,/ elf_flagdata(3E) 

/elf flagehdr, elf flagelf, elf^flagphdr, elf^flagscn,/ elf_flagdata(3E) 

/elf flagelf, elf_flagphdr^ elf^flagscn, elf^flagshdr/ elf_flagdata(3E) 

/elf__flagphdr, elf flagscn, elf^flagshdr manipulate flags elf_flagdata(3E) 

size of an object file type elf Jsi^e: elf32Jsi2e return the elf_fsize(3E) 

member header elf^getarhdr relieve archive elf_getarhdr(3E) 

symbol table elf_getai^ym retrieve arduve elf_getarsym(3E) 

m object file elf _j;etba8e get the base offset for elf_getbase(3E) 

elf rawdata get section dat;i elf getdata, elf newdata, elf_getdata(3E) 

^2_newehdr retrieve/ elf getehdr: elf32_getehdr, elf_getehdr(3E) 

identification data elf getident retrieve file elf_getident(3E) 

elf32_newphdr retrieve/ elf^getphdr: elf32_getphdr, elf_getphdr(3E) 

elfjtextscn get section/ elf^etscn, elf jidxscn> elf^newscft, elf_getscn(3E) 

dass-dependent section header elf getshdr: eif32_jet^dr retrieve elf^etshdr(3E) 

elf^hash compute hash value ............v...*.......... elf_hash(3E) 

elf^kind detefftiine i^e type elf2kiiid(3E) 

get section/ elf getscn, elf_ndxscn, elf^newsoi, eif^nextscn elf_getscn<3E) 

secti<^ data elf^etdata, elf_newdata, df_rawdata get df_getdata(3E) 

elf^tscn^ elf_ndxsat> dfjiewscti/ elf^nextscn get section/ ...v............ elf_getscn(3E) 
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access elf_next se(:^ii;enti^ ^rdiive member , elf_next(3E) 

elf getscn, elf ndxscn, elf newscn, elf^nextsen get section infonnation elf_getscn(3E) 

access elf ^yaiid random archive member ei£_rand(3E) 

elf_jgetdata, elf_newdata, elf^rawciata get section data elf _getdata(3E) 

£Qe contents elf rawfile retrieve uninterpreted i;lf_rawfile(3E) 

elf__strptr make a string pointer ftlf__strptr(3E) 

elf^wpd^te update an descriptor elf jipdate(3E) 

application versions elf_version coordinate Ul:^Tary and elf_v^ion(3E) 

elf32_xlatetom dass-dependent/ elf__xlate: elf32__xlatetot elf_xlate(3E) 

accounting acqt enaW^ or disable process , acct(2) 

crypt, setkey, encrypt generate encryption , crypt(3C) 

whether a character buffer is encrypted isencrypt determine , isencrypt(3G) 

crypt, setkey, encrypt generate encryption .., , crypt(3C) 

crypt password and file encryption functions , crypt(3X) 

program end, etext, edata last locations in , end(3C) 

/getgrgid, getgrnam, setgrent, endgrent, fgetgrent get group file/ , getgrent(3Q 

/getpwuid/ getpwnam, setpwent, endpwent, fgetpwent manipulate/ getpwent(3C) 

/getutline, pututline, setutent, endutent, utmpname access utmp file/ ,....„......, getut(30 

getdents read directory entries and put in a file system/ getdents(2) 

nlist get entries from name list nUst(3E) 

utmp, wtmp utmp ai\d wtmp entry forrnats utmp(4) 

endgrent, fgetgrent get group file entry /getgrnam, setgrent, getgrent(3Q 

getmntany get mnttab file entry getmntent, , getnmtent(3C) 

fgetpwent manipulate password file entry /setpwent, endpwent, ,.„...,....,....,. getpwent(3C) 

endutent, utmpname access utnip file entry /pututline, setutent, getut(3Q 

putpwent write password file entry „ putpwent(3C) 

imlink remove directory entry ., ,.,.,........,.....,..,....„.„.....,... unlink(2) 

environ user environment ,..„..,.t onyiron(5) 

fpsetsticky I^EIE floating-point environm<?nt control /fpgetsticky, ^t..... ....... fpgetroimd(3Q 

environ user environment ,., environ(5) 

getenv return value for environment name get^v(3C) 

putenv change or add value to twironinent putenv(3C) 

jrand48, srand4a, 9eed48,/ dr^d48, erand48, lrand48, nrand48, mrand48, drand48(3Q 

complementary error function erf, erfc error function ai:id », ...t.,.,.....,,,,,,^,.,.., erf(3M) 

complementary error function erf, erfc error fmiction and , erf(3M) 

error function erf, erfc error fmtction and complementary erf(3M) 

error function and coniplementary error function erf, erfc erf(3M) 

elf^errmsg, elf_ermo error handling elf_errmsg(3E) 

strerror get error message string strerror(3C) 

perror print system error messages perror<3Q 

introduction to system calls and error numbers intro intro(2) 

matherr error-handling function matherr(3M) 

strings, compressing or expanding escape codes /strcadd, strecpy copy strccpy(3G) 

line connection dial establish an out-going terminal ,. dial(30 

program end, etext, edata last locations in end(3C) 

hypot Euclidean distance function hypot(3M) 

cscope interactively examine a C program cscope<l) 

Permuted Index 9 



Permuted Index 



execlp, execvp execute a file exec: exed, execv, exede, execve, exec(2) 

execlp, execvp execute a/ exec: execl, execv, execle, execve, exec(2) 

execute a file exec: execl, execv, execle, execve, exedp, execvp exec(2) 

exec: exed, execv, exede, execve, exedp, execvp execute a file exec(2) 

files a.out ELF (Executable and Linking Format) a.out(4) 

execle, execve, execlp, execvp execute a file exec: exed, execv, exec(2) 

regcmp, regex compile and execute regtdar expression regcmp(3G) 

Iprof display line-by-line execution count profile data Iprof (1) 

sleep suspend execution for interval sleep(3Q 

monitor prepare execution profile monitor(3Q 

profil execution time profile profil(2) 

execvp execute a file exec: exed, execv, exede, execve, exedp, exec(2) 

file exec: exed, execv, exede, execve, execlp, execvp execute a exec(2) 

execv, exede, execve, exedp, execvp execute a file exec: exed, exec(2) 

create a new file or rewrite an existing one creat creat(2) 

exit, _exit terminate process exit(2) 

exit, _exit terminate process exit(2) 

loglOf, pow, powf, sqrt, sqrtf/ exp, expf, cbrt, log, logf, loglO, exp(3M) 

copy strings, compressing or expanding escape codes /strecpy strccpy(3G) 

loglOf, pow, powf, sqrt,/ exp, expf, cbrt, log, logf, loglO, exp(3M) 

/loglOf, pow, powf, sqrt, sqrtf exponential, logarithm, power,/ exp(3M) 

/compile, step, advance regular expression compile and match/ regexp(5) 

/compile, step, advance regular expression compile and match/ regexpr(3G) 

regcmp regular expression compile regcmp(l) 

regex compile and execute regular expression regcmp, regcmp(3G) 

/ceil, ceilf, copysign, fmod, fmodf, fabs, fabsf, rint, remainder floor,/ floor(3M) 

/ceilf, copysign, fmod, fmodf, fabs, fabsf, rint, remainder floor,/ floor(3M) 

data in a machine-independent fashion /sgetl access long integer sputl(3X) 

stream fdose, ffiush dose or flush a fdose(3S) 

fcnfl file control fcntl(2) 

fcntl file control options fcntl(5) 

number to string ecvt, fcvt, gcvt convert floating-point ecvt(3C) 

fopen, freopen, fdopen open a stream fopen(3S) 

status inquiries ferror, feof, dearerr, fileno stream ferror(3S) 

stream status inquiries ferror, feof, dearerr, fileno ferror(3S) 

fdose, fflush close or flush a stream fdose(3S) 

ffs find first set bit ffs(3C) 

from a stream getc, getchar, fgetc, getw get character or word getc(3S) 

/getgmam, setgrent, endgrent, fgetgrent get group file entry getgrent(3C) 

in a stream fsetpos, fgetpos reposition a file pointer fsetpos(3Q 

/getpwnam, setpwent, endpwent, fgetpwent manipulate password file/ getpwent(3C) 

gets, fgets get a string from a stream gets(3S) 

bufsplit split buffer into fields bufsplit(3G) 

mkfifo create a new FIFO mkfifo(3C) 

utime set file access and modification times utime(2) 

elf object file access library elf (3E) 

access determine accessibility of a file access(2) 
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chmod change mode of file chmod(2) 

chown change owner and group of a file chown(2) 

elf j-awfile retrieve uninterpreted file contents elf_rawfile(3E) 

fcnti file control fcntl(2) 

fcntl file control options fcntl(5) 

core core image file core(4) 

umask set and get file creation mask imiask(2) 

make a delta (change) to an SCCS file delta delta(l) 

close close a file descriptor close(2) 

dup duplicate an open file descriptor dup(2) 

dup2 duplicate an open file descriptor dup2(3Q 

elf_begin make a file descriptor elf begin (3E) 

elf_cntl control a file descriptor elf_cntl(3E) 

dump selected parts of an object file dump dimip(l) 

sact print current SCCS file editing activity sact(l) 

elf_end finish using an object file elf_end(3E) 

get the base offset for an object file elf getbase elf_getbase(3E) 

crypt password and file encryption fimctions crypt(3X) 

endgrent, fgetgrent get group file entry /getgmam, setgrent, getgrent(3Q 

getmntent, getmntany get nmttab file entry getnmtent(3C) 

fgetpwent manipulate password file entry /setpwent, endpwent^ getpwent(3C) 

endutent, utmpname access utmp file entry /pututline, setutent, getut(30 

putpwent write password file entry putpwent(3C) 

execve, execlp, execvp execute a file exec: exed^ execv, exede, exec(2) 

constants limits header file for implementation-spedfic limits(4) 

ar archive file format ar(4) 

intro introduction to file formats intro(4) 

get get a version of an SCCS file get(l) 

retrieve class-dependent object file header /elf32_newehdr elf_getehdr(3E) 

elf_5etident retrieve file identification data elf_getident(3E) 

pathfind search for named file in named directories pathfind(3G) 

copylist copy a file into memory copylist(3G) 

link link to a file Unk(2) 

the comment section of an object file mcs manipulate mcs(l) 

directory, or a spedal or ordinary file mknod make a mknod(2) 

ctermid generate file name for terminal ctermid(3S) 

mktemp make a unique file name mktemp(3C) 

nm print name list of an object file nm(l) 

ttyslot find the slot in the utmp file of the current user ttyslot(3C) 

creat create a new file or rewrite an existing one creat(2) 

the parent directory name of a file path name dimame report dimame(3G) 

fseek, rewind, ftell reposition a file pointer in a stream fseek(3S) 

fsetpos, fgetpos reposition a file pointer in a stream fsetpos(3Q 

Iseek move read/write file pointer ; lseek(2) 

prs print an SCCS file prs(l) 

read read from file read(2) 

remove remove file remove(3C) 

Permuted Index 11 
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rename rename file rename(3C) 

rmdel remove a delta from an SCCS file rmdel(l) 

compare two versions of an SCCS file sccsdiff sccsdiff(l) 

sccsfile format of SCCS file sccsfile(4) 

Stat, fstat get file status stat(2) 

iituxiber information from an object file /table, debugging and line strip(l) 

/read directory entries ahd put in a file system independent format getdents(2) 

ststtfs, fstatfs get file system information statfs(2) 

mount mount a file system mount(2) 

ustat get file system statistics ustat(2) 

sysfs get file system type information sysfs(2) 

vimount unmount a file system umount(2) 

tmpfile create a temporary file tmpfile(3S) 

create a name for a temf>orary file tmpnam, tempnam tmpnam(3S) 

cof2elf CORF to ELF object file translation cof2elf(l) 

ftw walk a file tree ftw(3C) 

return the size of an object file type elf_fsize: elf32_fsi2e elf_fsize(3E) 

elf_kind determine file type , elf_kind(3E) 

undo a previous get of an SCCS file unget ., unget(l) 

val validate an SCCS file val(l) 

write write on a file ..,....,....„., write(2) 

ferror, feof, clearerr, fileno stream status inquiries f error (3S) 

admin create and administer SCCS files admin(l) 

ELF (Executable and Linking Format) files a.out a.out(4) 

Id link editor for object files ld(l) 

lockf record locking on files , lockf(3Q 

section sizes in bytes of object files size print size(l) 

convert convert ardiive files to common formats convert(l) 

elf Jill set fill byte elf^fiU(3E) 

ffs find first set bit ffs(3C) 

ttyname, isatty find name of a terminal ttyname(3C) 

object library lorder find ordering relation for an lorder(l) 

the current user ttyslot find the slot in the utmp file of ttyslot(3C) 

elf_end finish using an object file elf_end(3E) 

deterinine/ isnan, isnand, isnanf, finite, fpclass, imordered isnan(3C) 

elf_flagshdr nfianipulate flags /elf_flagphdr, elf_flla^cn, elf_fl^gdata(3E) 

/^getsticky, fpsietsticky IEEE floating-point environment conbrol fpgetrouhd(3Q 

unordered d^erinine type of floating-point number /fpclass, isnan(3C) 

ecvt, fcvt, gcvt convert floating-point number to string ecvt(3C) 

scalb Hhanipulate parts of floating-point nimibers /nextafter, frexp(3C) 

/fmodf, fabs, fabsf, rint, remainder floor, ceiling, remainder, absolute/ floor(3M) 

copysipi, fmod, fmodf, fabs,/ floor, floorf, ceil, ceilf, floor(3M) 

fmod> fmodf, fabs, fabsf,/ floor, floorf, ceil, ceilf, copysign, floor(3M) 

cflow generate C flowgraph cflow(l) 

fclose, fflush dose Or flush a stream .i........... fdose(3S) 

/floorf, ceil, ceilf, copysigil, finod, fmodf, fabs, fabsf, rint,/ floor(3M) 

/ceil, ceilf, copysigtt, ftnod, fmodf, fabs, fabsf, rint, remainder/ ..........v...................... floor(3M) 
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for an application for use with fmtmsg /a list of severity levels addseverityOQ 

or system console fmtmsg display a message on stderr fmtmsg(3C) 

stream fopen, f reopen, fdopen open a fop>en(3S) 

fork create a new process fork(2) 

ar archive file format ar(4) 

a.out ELF (Executable and Linking Format) files a.out(4) 

put in a file system independent format /read directory entries and getdents(2) 

sccsfile format of SCCS file sccsfile(4) 

convert archive files to common formats convert convert(l) 

intro introduction to file formats intro(4) 

utmp, wtmp utmp and wtmp entry formats utmp(4) 

scanf, fscanf, sscanf convert formatted input scanf(3S) 

vprintf, vfprintf, vsprintf print formatted output of a variable/ vprintf(3S) 

printf, fprintf, sprintf print formatted output printf(3S) 

localeconv get numeric formatting information localeconv(3C) 

of/ isnan, isnand, isnanf, finite, fpclass, unordered determine type isnan(3Q 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky,/ fpgetround(30 

fpsetmask, fpgetsticky,/ fpgetround, fpsetround, fpgetmask, fpgetround(3Q 

/fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky IEEE/ fpgetround(3Q 

output printf, 4>rintf, sprintf print formatted printf(3S) 

fpgetroimd, fpsetrotmd, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky/ fpgetroimd(3Q 

fpgetsticky,/ fpgetroimd, fpsetround, fpgetmask, fpsetmask, fpgetroimd(3Q 

/fpgetmask, fpsetmask, fpgetsticky, fpsetsticky IEEE floating-point/ fpgetround(30 

on a stream putc, putchar, fputc, putw put character or word putc(3S) 

puts, fputs put a string on a stream puts(3S) 

fread, fwrite binary input/output fread(3S) 

mallinfo memory allocator malloc, free, realloc, calloc, mallopt, malloc(3X) 

allocator malloc, free, realloc, calloc memory malloc(3C) 

fopen, freopen, fdopen open a stream fopen(3S) 

nextafter, scalb manipulate parts/ frexp, Idexp, logb, modf, modff, frexp(3Q 

input scanf, fscanf, ^canf convert formatted scanf(3S) 

file pointer in a stream fseek, rewind, fteU reposition a fseek(3S) 

pointer in a stream fsetpos, fgetpos reposition a file fsetpos(3Q 

Stat, fstat get file status stat(2) 

statfs, fstatfs get file system information statfs(2) 

a stream fseek, rewind, fteU reposition a file pointer in fseek(3S) 

communication package stdipc: ftok standard interprocess stdipc(3C) 

ftw walk a fUe tree ftw(3C) 

function erf, erfc error function and complementary error erf(3M) 

function and complementary error function erf, erfc error erf(3M) 

gamma, Igamma log gamma function gamma(3M) 

hypot Euclidean distance function hypK)t(3M) 

libwindows windowing terminal fvmction library libwindows(3X) 

matherr error-handling function malherr(3M) 

prof profile within a function prof(5) 

math math functions and constants math(5) 

intro introduction to functions and libraries , intro(3) 
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jO, jl, jn, yO, yl, yn Bessel fiinctions bessel: bessel(3M) 

crypt password and file encryption functions crypt(3X) 

logarithm, power, square root functions /sqrt, sqrtf exponential, exp(3M) 

ceiling, ren\ainder, absolute value functions /rint, remainder floor, floor(3M) 

mbstowcs, wcstombs multibyte string functions mbstring: mbstring(3Q 

asinh, acosh, atanh hyperbolic functions /coshf, tanh, tanhf, siiUi(3M) 

atanf, atan2, atan2f trigonometric functions /acos, acosf, atan, trig(3M) 

fread, fwrite binary input/output fread(3S) 

gamma, Igamma log gamma function gamma(3M) 

gamma, Igamma log gamma function gamma(3M) 

to string ecvt, fcvt, gcvt convert floating-point number ecvt(3C) 

signal abort generate an abnormal termination abort(3C) 

cflow generate C flowgraph cflow(l) 

cxref generate C program cross-reference cxref (1) 

and conversion tables chrtbl generate character classification chrtbl(lM) 

crj^t, setkey, encrypt generate encryption ciypt(3C) 

ctermid generate file name for terminal ctermid(3S) 

lexical tasks lex generate programs for simple lex(l) 

/jrand48, srand48, seed48, lcong48 generate tmiformly distributed/ drand48(3C) 

rand, srand simple random-number generator rand(3C) 

character or word from a stream getc, getchar, fgetc, getw get getc(3S) 

or word from a stream getc, getchar, fgetc, getw get character getc(3S) 

working directory getcwd get pathname of current getcwd(3Q 

put in a file system independent/ getdents read directory entries and getdents(2) 

user,/ getuid, geteuid, getgid, getegid get real user, effective getuid(2) 

name getenv return value for environment getenv(3Q 

user, effective user, real/ getuid, geteuid, getgid, getegid get real getuid(2) 

effective user,/ getuid, geteuid, getgid, getegid get real user, getuid(2) 

setgrent, endgrent, fgetgrent get/ getgrent, getgrgid, getgrnam, getgrent(3C) 

endgrent, fgetgrent get/ getgrent, getgrgid, getgrnam, setgrent, getgrent(3C) 

fgetgrent get/ getgrent, getgrgid, getgrnam, setgrent, endgrent, getgrent(3C) 

getlogin get login name getlogin(3C) 

getmntent, getmntany get mnttab file entry getmntent(3C) 

file entry getmntent, getiimtany get mnttab getmntent(3C) 

stream getmsg get next message off a getmsg(2) 

argument vector getopt get option letter from getopt(3Q 

getpass read a password getpass(3C) 

process group, and parent/ getpid, getpgrp, getppid get process, getpid(2) 

process, process group, and parent/ getpid, getpgrp, getppid get getpid(2) 

and parent/ getpid, getpgrp, getppid get process, process group, getpid(2) 

getpw get name from UID getpw(3Q 

setpwent, endpwent, fgetpwent/ getpwent, getpwuid, getpwnam, getpwent(3C) 

fgetpwent/ getpwent, getpwuid, getpwnam, setpwent, endpwent, getpwent(3C) 

endpwent, fgetpwent/ getpwent, getpwuid^ getpwnam, setpwent, getpwent(3C) 

stream gets, f gets get a string from a gets(3S) 

string getsubopt parse suboptions from a getsubopt(3C) 

get real user, effective user,/ getuid, geteuid, getgid, getegid getuid(2) 
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getutline, pututline, setutent,/ getut: getutent, getutid, getut(3Q 

pututline, setutent,/ getut: getutent, getutid, getutline, getut(30 

setutent,/ getut: getutent, getutid, getutline, pututline, getut(3Q 

getut: getutent, getutid, getutline, pututline, setutent,/ getutOQ 

stream getc, getchar, fgetc, getw get character or word from a getc(3S) 

gmatch shell g;lobal pattern matching gmatch(3G) 

matching gmatch shell global pattern gmatch (3G) 

and time to/ ctime, localtime, gmtime, asctime, tzset convert date ctime(3C) 

setjmp, longjmp non-local goto setjmp(3C) 

/get real user, effective user, real group, and effective group IDs getuid(2) 

/getppid get process, process group, and parent process IDs getpid(2) 

setgrent, endgrent, fgetgrent get group file entry /getgmam, getgrent(3Q 

setpgrp set process group ID setpgrp(2) 

user, real group, and effective group IDs /get real user, effective getuid(2) 

setuid, setgid set user and group IDs setuid(2) 

chown change owner and group of a fQe chown(2) 

send a signal to a process or a group of processes kill kill(2) 

maintain, update, and regenerate groups of programs make make(l) 

ssignal, gsignal software signals ssignaI(3Q 

stdarg handle variable argument list stdarg(5) 

varargs handle variable argument list varargs(5) 

isprint, isgraph, isascii character handling /iscntrl, ispunct, ctype(3Q 

elf_errmsg, elf_ermo error handling elf_errmsg(3E) 

mblen, wctomb multibyte character handling mbchar: mbtowc, mbchar(3C) 

hsearch, hcreate, hdestroy manage hash search tables hsearch(3C) 

elf_hash compute hash value elf_hash(3E) 

search tables hsearch, hcreate, hdestroy manage hash hsearch(3C) 

hsearch, haeate, hdestroy manage hash search tables hsearch(3C) 

retrieve archive member header elf_getarhdr elf_getarhdr(3E) 

class-dependent object file header / elf32_newehdr retrieve elf_getehdr(3E) 

retrieve class-dependent section header elf_getshdr: elf32_getshdr elf_getshdr(3E) 

implementation-specific/ limits header file for limits(4) 

retrieve dass-dependent program header table /elf32_newphdr elf_getphdr(3E) 

numbers or SCCS commands help ask for help with message help(l) 

commands help ask for help with message numbers or SCCS help(l) 

layers protocol used between host and windowing terminal imder/ layers(5) 

jagent host control of windowing terminal jagent(5) 

hash search tables hsearch, hcreate, hdestroy manage hsearch(3C) 

tanhf, asinh, acosh, atanh hyperbolic functions /tanh, sinh(3M) 

hypot Euclidean distance function hypot(3M) 

setpgrp set process group ID setpgrp(2) 

elf_getident retrieve file identification data elf_getident(3E) 

what print identification strings what(l) 

shmget get shared memory segment identifier shmget(2) 

process group, and parent process IDs /getpgrp, getppid get process, getpid(2) 

real group, and effective group IDs /get real user, effective user, getuid(2) 

setuid, setgid set user and group IDs setuid(2) 
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/fpsetmask, fpgetsticky, fpsetsticky IEEE floating-point environment/ fpgetround(3Q 

core core image file core(4) 

limits header file for implementation-specific constants limits(4) 

entries and put in a file system independent format /read directory getdents(2) 

elf_newscn, elf_nextscn get section information /elf ndxscn, elf_getscn(3E) 

/table, debugging and line number information from an object file strip(l) 

localeconv get numeric formatting information localeconv(3C) 

statfs, fstatfs get file system information statfs(2) 

sysfs get file system type information sysfs(2) 

popen, pclose initiate pipe to/from a process popen(3S) 

fscanf, sscanf convert formatted input scanf, scanf(3S) 

ungetc push character back onto input stream ungetc(3S) 

fread, fwrite binary input/output fread(3S) 

poll STREAMS input/output multiplexing poll(2) 

stdio standard buffered input/output package stdio(3S) 

dearerr, fileno stream status inquiries ferror, feof, ferror(3S) 

insque, remque insert /remove element from a queue insque(3C) 

element from a queue insque, remque insert/ remove insque(3C) 

install install commands install(lM) 

install install commands install(lM) 

abs, labs return integer absolute value abs(3C) 

a641, 164a convert between long integer and base-64 ASCII string a641(3Q 

sputl, sgetl access long integer data in a/ sputl(3X) 

atol, atoi convert string to integer strtol, strtoul, strtol(3C) 

13tol, ItoB convert between 3-byte integers and long integers 13tol(3Q 

between 3-byte integers and long integers 13tol, ltol3 convert 13tol(30 

cscope interactively examine a C program cscope(l) 

pipe create an interprocess channel pipe(2) 

stdipc: ftok standard interprocess communication package stdipc(3Q 

sleep suspend execution for interval sleep(30 

intro introduction to file formats intro(4) 

libraries intro introduction to functions and intro(3) 

intro introduction to miscellany intro(5) 

commands intro introduction to programming intro(l) 

and error nimibers intro introduction to system calls intro(2) 

library intro introduction to the math intro(3M) 

intro introduction to file formats intro(4) 

libraries intro introduction to functions and intro(3) 

intro introduction to miscellany intro(5) 

commands intro introduction to programming intro(l) 

error numbers intro introduction to system calls and intro(2) 

intro introduction to the math library intro(3M) 

ioctl control device ioctl(2) 

/islower, isupper, isalpha, isalnum, isspace, iscntrl, ispunct,/ ctype(30 

/isxdigit, islower, isupper, isalpha, isalnum, isspace, iscntrl,/ ct)rpe(30 

/iscntrl, ispimct, isprint, isgraph, isasdi character handling ctype(3Q 

ttyname, isatty find name of a terminal ttyname(3C) 
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/isupper, isalpha, isalnum, isspace, iscntrl, ispimct, isprint isgraph,/ ctype(3Q 

isupper^ isalpha^ isalnum^ ctype: isdigit isxdigit islower, ct)rpe(3Q 

character buffer is encrypted isencr)rpt determine whether a isencrypt(3G) 

/isspace, iscntrl, ispimct, isprint isgraph/ isasdi character handling ctype(30 

isspace,/ ctype: isdigit, isxdigit, islower, isupper, isalpha, isalntm:i, ctype(30 

fpdass, unordered determine type/ isnan, isnand, isnanf, finite, isnan(3C) 

unordered determine type of/ isnan, isnand, isnanf, finite, Qxdass, isnan(3C) 

determine type of/ isnan, isnand, isnanf, finite, fpdass, imordered isnan(3C) 

/isalnum, isspace, iscntrl, ispimct, isprint, isgraph, isasdi character/ ctype(3Q 

/isalpha, isalnum, isspace, iscntrl, ispunct, isprint, isgraph, isasdi/ ctype(3Q 

/islower, isupper, isalpha, isalnum, isspace, iscntrl, ispunct, isprint,/ ctype(3Q 

system issue a shell command system(3S) 

ctype: isdigit, isxdigit, islower, isupper, isalpha, isalnum, isspace,/ ctype(30 

isalpha, isalnum,/ ctype: isdigit, isxdigit, islower, isupper, ctype(30 

functions bessel: jO, jl, jn, yO, yl, yn Bessd bessel(3M) 

bessel: jO, jl, jn, yO, yl, yn Bessel functions bessel(3M) 

terminal jagent host control of windowing jagent(5) 

bessel: jO, jl, jn, yO, yl, yn Bessel functions bessel(3M) 

/erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48/ drand48(30 

a group of processes kill send a signal to a process or kill(2) 

integers and long integers 13tol, ItoB convert between 3-byte 13tol(30 

and base-64 ASCII string a641, 164a convert between long integer a641(30 

abs, labs return integer absolute value abs(30 

strftime language specific strings strftime(4) 

and windowing terminal under/ layers protocol used between host layers(5) 

host and windowing terminal under layers(l) /protocol used between layers(5) 

/mrand48, jrand48, srand48, seed48, lcong48 generate uniformly/ drand48(30 

Id link editor for object files ld(l) 

nextafter, scalb manipulate/ frexp, Idexp, logb, modf, modff, frexp(30 

remainder div, Idiv compute the quotient and div(30 

getopt get option letter from argument vector getopt(3C) 

with/ /build a list of severity levels for an application for use addseverity(3Q 

lexical tasks lex generate programs for simple lex(l) 

lex generate programs for simple lexical tasks lex(l) 

Isearch, Ifind linear search and update lsearch<3C) 

gamma, Igamma log gamma function gamma(3M) 

intro introduction to functions and libraries intro(3) 

elf_version coordinate library and application versions elf_version(3E) 

ar maintain portable archive or library ar(l) 

elf object file access library elf(3E) 

intro introduction to the math library intro(3M) 

windowing terminal function library libwindows libwindows(3X) 

ordering relation for an object library lorder find lorder(l) 

function library libwindows windowing terminal libwindows(3X) 

implementation-specific constants limits header file for limits(4) 

ulimit get and set user limits ulimit(2) 

establish an out-going terminal line connection dial dial(3Q 
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/strip symbol table, debugging and line number information from an/ strip(l) 

Isearch, Ifind linear search and update lsearch(3C) 

profQe data Iprof display line-by-line execution count Iprof(l) 

Id Uvk editor for object files ld(l) 

link link to a file link(2) 

Unk link to a file link(2) 

a.out ELF (Executable and Linking Format) files a.out(4) 

lint a C program checker lint(l) 

nlist get entries from name list nlist(3E) 

run print name list of an object file nm(l) 

application/ addseverity build a list of severity levels for an addseverity(3C) 

stdarg handle variable argument list stdarg(5) 

varargs handle variable argument list varargs(5) 

output of a variable argument list /vsprintf print formatted vprintf(3S) 

modify and query a program's locale setlocale setlocale(3C) 

information localeconv get numeric formatting localeconv(3C) 

convert date and time to/ ctime, localtime, gmtime, asctime, tzset ctime(3C) 

end, etext, edata last locations in program end(3Q 

memory plock lock process, text, or data in plock(2) 

lockf record locking on files lockf(30 

maillock manage lockfile for user's mailbox maillock(3X) 

lockf record locking on files lockf(3Q 

gamma, Igamma log gamma function gamma(3M) 

powf, sqrt, sqrtf/ exp, expf, cbrt, log, logf, loglO, loglOf, pow, exp(3M) 

sqrtf/ exp, expf, cbrt, log, logf, loglO, loglOf, pow, powf, sqrt, exp(3M) 

exp, expf, cbrt, log, logf, loglO, loglQf, pow, powf, sqrt, sqrtf/ exp(3M) 

/pow, powf, sqrt, sqrtf exponential, logarithm, power, square root/ exp(3M) 

manipulate parts of/ frexp, Idexp, logb, modf, modff, nextafter, scalb frexp(3C) 

sqrt, sqrtf/ exp, expf, cbrt, log, logf, loglO, loglOf, pow, powf, exp(3M) 

getlogin get login name getlogin(3C) 

cuserid get character login name of the user cuserid(3S) 

setjmp, longjmp non-local goto setjmp(3C) 

an object library lorder find ordering relation for lorder(l) 

execution count profile data Iprof display line-by-line Iprof (1) 

srand48, seed48,/ drand48, erand48, kand48, nrand48, mrand48, jrand48, drand48(3C) 

update Isearch, Ifind linear search and lsearch(3C) 

Iseek move read /write file pointer lseek(2) 

integers and long integers 13tol, ltol3 convert between 3-byte 13tol(3Q 

m4 macro processor m4(l) 

values machine-dependent values values(5) 

sgetl access long integer data in a machine-independent fashion sputl, sputl(3X) 

m4 macro processor m4(l) 

maillock manage lockfile for user's mailbox maillock(3X) 

mailbox maillock manage lockfile for user's maillock(3X) 

library ar maintain portable archive or ar(l) 

groups of programs make maintain, update, and regenerate make(l) 

free, realloc, calloc, mallopt, mallinfo memory allocator malloc, malloc(3X) 
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mallopt, mallinfo memory allocator malloc, free, realloc, calloc, malloc(3X) 

memory allocator malloc, free, realloc, calloc malloc(3C) 

malloc, free, realloc, caUoc, mallopt, mallinfo memory allocator malloc(3X) 

tsearch, tfind, tdelete, twalk manage binary search trees tsearch(3C) 

hsearch, hcreate, hdestroy manage hash search tables hsearch(3C) 

maillock manage lockfile for user's mailbox maillock(3X) 

sigignore, sigpause signal management /sighold, sigrelse, sigset(2) 

elf flagscn, elf flagshdr manipulate flags /elf_flagphdr, elf_flagdata(3E) 

/logb, modf, modff, nextafter, scalb manipulate parts of floating-point/ frexp(3Q 

/setpwent, endpwent, fgetpwent manipulate password file entry getpwent(3C) 

an object file mcs manipulate the comment section of mcs(l) 

strfind, strrspn, strtrns string manipulations str: str(3G) 

asdi map of ASCII character set ascii(5) 

timask set and get file creation mask ximask(2) 

regular expression compile and match routines /step, advance regexp(5) 

regular expression compile and match routines /step, advance regexpr(3G) 

gmatdi shell global pattern matching gmatch(3G) 

math math functions and constants math(5) 

intro introduction to the math library intro(3M) 

math math functions and constants math(5) 

matherr error-handling function matherr(3M) 

multibyte character handling mbchar: mbtowc, mblen, wctomb mbchar(3C) 

handling mbchar: mbtowc, mblen, wctomb multibyte character mbchar(3C) 

functions mbstring: mbstowcs, wcstombs multibyte string mbstring(3C) 

multibyte string functions mbstring: mbstowcs, wcstombs mbstring(3C) 

character handling mbchar: mbtowc, mblen, wctomb multibyte mbchar(3C) 

of an object file mcs manipulate the comment section mcs(l) 

elf_next sequential archive member access elf_next(3E) 

elf_rand random archive member access elf_rand(3E) 

elf getarhdr retrieve archive member header elf_getarhdr(3E) 

offsetof offset of structure member offsetof(3C) 

memmove, memset memory/ memory: memccpy, memchr, memcmp, memcpy, memory(3Q 

memset memory/ memory: memccpy, memchr, memcmp, memcpy, memmove, memory(3Q 

memory/ memory: memccpy, memdir, memcmp, memcpy, memmove, memset memory(3Q 

memory: memccpy, memchr, memcmp, memcpy, memmove, memset memory/ memory(3Q 

/memccpy, memchr, memcmp, memcpy, memmove, memset memory operations memory(3Q 

malloc, free, realloc, calloc memory allocator malloc(3C) 

realloc, calloc, mallopt, mallinfo memory allocator malloc, free, malloc(3X) 

shmcfl shared memory control operations shmctl(2) 

copylist copy a file into memory copylist(3G) 

memcpy, memmove, memset memory/ memory: memccpy, memchr, memcmp, memory(3Q 

memcmp, memcpy, memmove, memset memory operations /memccpy, memchr, memory(3Q 

shmop shared memory operations shmop(2) 

lock process, text, or data in memory plock plodk(2) 

shmget get shared memory segment identifier shmget(2) 

memchr, memcmp, memcpy, memmove, memset memory operations /memccpy, memory(3Q 

msgctl message control operations msgctl(2) 
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help ask for help with message numbers or SCCS commands help(l) 

getmsg get next message off a stream getmsg(2) 

putmsg send a message on a stream putmsg(2) 

fmtmsg display a message on stderr or system console fmtmsg(3C) 

msgop message operations msgop(2) 

msgget get message queue msgget(2) 

strerror get error message string strerror(3Q 

perror print system error messages perror(3C) 

intro introduction to miscellany intro(5) 

mkdir make a directory mkdir(2) 

directories in a path mkdirp, rmdirp create, remove mkdirp(3G) 

mkfifo create a new FIFO mkfifo(3C) 

special or ordinary file mknod make a directory, or a mknod(2) 

mktemp make a imique file name mktemp(3C) 

calendar time mktime converts a tm structure to a mktime(3C) 

getmntent, getmntany get mnttab file entry getmntent(30 

chmod change mode of file chmod(2) 

manipulate/ frexp, Idexp, logb, modf, modff, nextafter, scalb frexp(3C) 

parts of/ frexp, Idexp, logb, modf, modff, nextafter, scalb manipulate frexp(3C) 

utime set file access and modification times utime(2) 

setlocale modify and query a program's locale setlocale(3C) 

montbl create monetary database montbl(lM) 

monitor prepare execution profile monitor(3Q 

montbl create monetary database montbl(lM) 

moimt mount a file system mount(2) 

moimt mount a file system mount(2) 

Iseek move read/write file pointer lseek(2) 

drand48, erand48, kand48, nrand48, mrand48, jrand48, srand48, seed48,/ drand48(3C) 

msgctl message control operations msgctl(2) 

msgget get message queue msgget(2) 

msgop message operations msgop(2) 

mbchar: mbtowc, mblen, wctomb multibyte character handling mbchar(3C) 

mbstring: mbstowcs, wcstombs multibyte string functions mbstring(30 

by xt driver xtproto multiplexed channels protocol used xtproto(5) 

poll STREAMS input/output multiplexing , poll(2) 

return the last element of a path name basename basename(3G) 

directory name of a file path name dimame report the parent dimame(3G) 

tmpnam, tempnam create a name for a temporary file tmpnam(3S) 

ctermid generate file name for terminal ctermid(3S) 

getpw get name from UID getpw(3Q 

getenv return value for environment name getenv(3Q 

getlogin get login name getlogin(3C) 

nlist get entries from name list rdist(3E) 

nm print name list of an object file nm(l) 

mktemp make a imique file name mktemp(3C) 

dimame report the parent directory name of a file path name dimame(3G) 

tt)mame, isatty find name of a terminal tt)mame(3Q 
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uname get name of current UNIX system imame(2) 

cuserid get character login name of the user cuserid(3S) 

pathfind search for named file in named directories pathfind(3G) 

pathfind search for named file in named directories pathfind(3G) 

bgets read stream up to next delimiter bgets(3G) 

getmsg get next message off a stream getmsg(2) 

frexp, Idexp, logb, modf, modff, nextafter, scalb manipulate parts/ frexp(30 

nice change priority of a process nice(2) 

nlist get entries from name list nlist(3E) 

file nm print name list of an object nm(l) 

setjmp, longjmp non-local goto setjmp(3C) 

seed48,/ drand48, erand48, b-and48, nrand48, mrand48, jrand48, srand48, drand48(30 

/symbol table, debugging and line number information from an object/ strip(l) 

determine type of floating-point number /finite, fpclass, imordered isnan(3Q 

convert string to double-precision nimiber strtod, atof, strtod(3C) 

fcvt, gcvt convert floating-poiht nimiber to string ecvt, ecvt(3Q 

imiformly distributed pseudo-random numbers /seed48, lcong48 generate drand48(3Q 

manipulate parts of floating-point numbers /modff, nextafter, scalb frexp(3Q 

to system calls and error numbers intro introduction intro(2) 

help ask for help with message numbers or SCCS commands help(l) 

localeconv get numeric formatting information localeconv(3C) 

dis object code disassembler dis(l) 

elf object fQe access library elf(3E) 

dump dump selected parts of an object file dump(l) 

elf_end finish using an object file elf_end(3E) 

get the base offset for an object fQe elf_getbase elf_getbase(3E) 

retrieve class-dependent object fQe header /elf32_newehdr elf_getehdr(3E) 

the comment section of an object fQe mcs manipulate mcs(l) 

nm print name list of an object fQe nm(l) 

and line number information from an object fQe /table, debugging strip(l) 

cof2elf COFF to ELF object file translation cof2elf(l) 

elf32_fsize return the size of an object fQe type elf_fsize: elf_fsize(3E) 

Id link editor for object fQes ld(l) 

print section sizes in bytes of object fQes size size(l) 

find ordering relation for an object library lorder lorder(l) 

elf^getbase get the base offset for an object file elf_getbase(3E) 

offsetof offset of structure member offsetof(3Q 

offsetof offset of structure member offsetof(3Q 

imgetc push character back onto input stream vmgetc(3S) 

fopen, freopen, fdopen open a stream fopen(3S) 

command p2open, p2close open, dose pipes to and from a p2open(3G) 

dup duplicate an open file descriptor dup(2) 

dup2 duplicate an open file descriptor dup2(3Q 

open open for reading or writing open(2) 

open open for reading or writing open(2) 

rewinddir, closedir/ directory: opendir, readdir, telldir, seekdir, directory(3Q 

rewinddir, closedir directory operations /telldir, seekdir, directory(30 
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memcpy, memmove, memset memory operations /memchr, memcmp, memory(3Q 

msgctl message control operations msgctl(2) 

msgop message operations msgop(2) 

semctl semaphore control operations semctl(2) 

semop semaphore operations semop(2) 

shmctl shared memory control operations shmctl(2) 

shmop shared memory operations shmop(2) 

strcspn, strtok, strstr string operations /strpbrk, strspn, string(3C) 

getopt get option letter from argument vector getopt(3C) 

fcntl file control options fcntl(5) 

library lorder find ordering relation for an object lorder(l) 

make a directory, or a special or ordinary file mknod mknod(2) 

dial establish an out-going terminal line connection dial(3Q 

/vfprintf, vsprintf print formatted output of a variable argument Ust vprintf(3S) 

fprintf, sprintf print formatted output printf, printf(3S) 

chown change owner and group of a file chown(2) 

from a command p2open, p2dose open, dose pipes to and p2open(3G) 

to and from a command p2open, p2dose open, dose pipes p2open(3G) 

standard buffered input/output package stdio stdio(3S) 

standard interprocess commtinication package stdipc: ftok stdipc(3Q 

path name dirname report the parent directory name of a file dimame(3G) 

get process, process group, and parent process IDs /getppid getpid(2) 

getsubopt parse suboptions from a string getsubopt(3C) 

dump dump selected parts of an object file dvtmp(l) 

/modff, nextafter, scalb manipulate parts of floating-point ntunbers frexp(3C) 

fimctions crypt password and file encryption crypt(3X) 

endpwent, fgetpwent manipulate password file entry /setpwent, getpwent(3C) 

putpwent write password file entry putpwent(3C) 

getpass read a password getpass(3C) 

create, remove directories in a path mkdirp, rmdirp mkdirp(3G) 

return the last element of a path name basename basename(3G) 

the parent directory name of a file path name dirname report dimame(3G) 

named directories pathfind search for named file in pathfind(3G) 

directory getcwd get pathname of current working getcwd(3Q 

gmatdi shell global pattern matching gmatch(3G) 

pause suspend process until signal pause(2) 

process popen, pdose initiate pipe to/from a popen(3S) 

perror print s)rstem error messages perror(3Q 

pipe create an interprocess channel pipe(2) 

popen, pdose initiate pipe to/from a process popen(3S) 

p2open, p2dose open, dose pipes to and from a command p2open(3G) 

in memory plock lock process, text, or data plock(2) 

elf strptr make a string pointer elf_strptr(3E) 

rewind, ftell reposition a file pointer in a stream fseek, fseek(3S) 

fsetpos, fgetpos reposition a file pointer in a stream fsetpos(3Q 

Iseek move read/ write file pointer lseek(2) 

multiplexing poll STREAMS input/output poll(2) 
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a process popen, pclose initiate pipe to/from popen(3S) 

ar maintain portable archive or library ar(l) 

/cbrt, log, logf, loglO, loglQf, pow, powf, sqrt, sqrtf exponential,/ exp(3M) 

sqrt, sqrtf exponential, logarithm, power, square root functions /powf, exp(3M) 

/log, logf, loglO, loglQf, pow, powf, sqrt, sqrtf exponential,/ exp(3M) 

monitor prepare execution profile monitor(30 

unget undo a previous get of an SCC5 file tmget(l) 

types primitive system data types types(5) 

prs print an SCCS file prs(l) 

activity sact print current SCCS file editing sact(l) 

vprintf, vfprintf, vsprintf print formatted output of a/ vprintf(3S) 

printf, fprintf, sprintf print formatted output printf(3S) 

what print identification strings what(l) 

nm print name list of an object file nm(l) 

object files size print section sizes in bytes of size(l) 

perror print system error messages perror(3C) 

formatted output printf, fprintf, sprintf print printf(3S) 

nice change priority of a process nice(2) 

acct enable or disable process accounting , acct(2) 

alarm set a process alarm clock alarm (2) 

times get process and child process times times(2) 

exit, exit terminate process exit(2) 

fork create a new process fork(2) 

IDs /getpgrp, getppid get process, process group, and parent process getpid(2) 

setpgrp set process group ID setpgrp(2) 

process, process group, and parent process IDs /getpgrp, getppid get getpid(2) 

nice change priority of a process nice(2) 

kill send a signal to a process or a group of processes kill(2) 

pclose initiate pipe to/from a process popen, popen(3S) 

getpid, getpgrp, getppid get process, process group, and parent/ getpid(2) 

plock lock process, text, or data in memory plock(2) 

times get process and child process times times(2) 

wait wait for child process to stop or tenninate wait(2) 

ptrace process trace ptrace(2) 

pause suspend process until signal pause(2) 

a signal to a process or a group of processes kill send kill(2) 

m4 macro processor m4(l) 

prof display profile data prof(l) 

prof profile within a function prof (5) 

profil execution time profile profil(2) 

line-by-line execution count profile data Iprof display Iprof(l) 

prof display profile data prof(l) 

monitor prepare execution profile monitor (3Q 

profil execution time profile profil(2) 

prof profile within a ftmction prof (5) 

assert verify program assertion assert(3X) 

cb C program beautifier cb(l) 
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lint a C program checker lint(l) 

cxref generate C program cross-reference cxref(l) 

cscope interactively examine a C program cscope(l) 

ctrace C program debugger ctrace(l) 

end, etext, edata last locations in program end(3Q 

retrieve class-dependent program header table /elf32_newphdr elf_getphdr(3E) 

raise send signal to program raise(3Q 

atexit add program termination routine atexit(3C) 

intro introduction to programming commands intro(l) 

lex generate programs for simple lexical tasks lex(l) 

setlocale modify and query a program's locale setlocale(3C) 

update, and regenerate groups of progiams make maintain, make(l) 

windowing terminal vmder/ layers protocol used between host and layers(5) 

xtproto multiplexed channels protocol used by xt driver xtproto(5) 

prs print an SCCS file prs(l) 

generate uniformly distributed pseudo-random numbers /lcong48 drand48(3C) 

ptrace process trace ptrace(2) 

stream ungetc push character back onto input ungetc(3S) 

puts, fputs put a string on a stream puts(3S) 

putQ putchar, fputc, putw put cliaracter or word on a stream putc(3S) 

getdents read directory entries and put in a file system indep>endent/ getdents(2) 

character or word on a stream pule, putchar, fpulc, putw put putc(3S) 

or word on a stream putc, putchar, fputc, putw put character putc(3S) 

environment putenv change or add value to putenv(3C) 

putmsg send a message on a stream putmsg(2) 

putpwent write password file entry putpwent(3C) 

stream puts, fputs put a string on a puts(3S) 

/getutent, getutid, getutline, pututline, setutent, endutent,/ , getut(3Q 

stream putc, putchar, fputc, putw put character or word on a putc(3S) 

qsort quicker sort qsort(3C) 

setlocale modify and query a program's locale setlocale(3C) 

remque insert/remove element from a queue insque, insque(3C) 

nrisgget get message queue msgget(2) 

qsort quicker sort qsort(3C) 

div, Idiv compute the quotient and remainder div(3Q 

raise send signal to program raise(3Q 

generator rand, srand simple random-number rand(3C) 

elf rand random archive member access elf jrand(3E) 

rand, srand simple random-mmiber generator rand(3C) 

getpass read a password getpass(3C) 

file system independent/ getdents read directory entries and put in a getdents(2) 

read read from file read(2) 

read read from file read(2) 

bgets read stream up to next delimiter bgets(3G) 

rewinddir,/ directory: opendir, readdir, telldir, seekdir, directory(3C) 

open open lor reading or writing , open(2) 

Iseek move read/write file pointer lseek(2) 
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/get real user, effective user, real group, and effective group IDs getuid(2) 

/geteuid, getgid, getegid get real user, effective iiser, real/ getuid(2) 

memory allocator malloc, free, realloc, calloc, mallopt, mallinfo malloc(3X) 

malloc, free, realloc, calloc memory allocator malloc(3C) 

signal specify what to do upon receipt of a signal signal(2) 

lodcf record locking on files lockfOO 

regular expression regcmp, regex compile and execute regcmp(3G) 

regcmp regular expression compile regcmp(l) 

make maintain, update, and regenerate groups of programs make(l) 

expression regcmp, regex compile and execute regular regcmp(3G) 

regular expression compile and/ regexp: compile, step, advance regexp(5) 

regular expression compile and/ regexpr: compile, step, advance regexpr(3G) 

regexp: compile, step, advance regular expression compile and/ regexp(5) 

regexpr: compile, step, advance regular expression compile and/ regexpr(3G) 

regcmp regular expression compile regcmp(l) 

regcmp, regex compile and execute regular expression regcmp(3G) 

lorder find ordering relation for an object library lorder(l) 

/rint, remainder floor, ceiling, remainder, absolute Value functions floor (3M) 

div, Idiv compute the quotient and remainder , div(3Q 

/fmod, fmodf, fabs, fabsf, rint, remainder floor, ceiling,/ floor(3M) 

rmdel remove a delta from an SCCS file rmdel(l) 

rmdir remove a directory rmdir(2) 

mkdirp, rmdirp create, remove directories in a path mkdirp(3G) 

unlink remove directory entry unlink(2) 

remove remove file remove(3C) 

remove remove file remoVe(3C) 

queue insque, remque insert/remove element from a insque(3C) 

rename rename file rename(3C) 

rename rename file , rename(3C) 

clock report CPU time used dock(3Q 

a file path name dirname report the parent directory name of dimame(3G) 

stream fseek, rewind, ftell reposition a file pointer in a fseek(3S) 

stream fsetpos, fgetpos reposition a file pointer in a fsetpos(30 

elf^etarhdr retrieve archive member header elf_^tarhdr(3E) 

eliF_^etarsym retrieve archive symbol table elf_getarsym(3E) 

file/ /elf32^et6hdr, elf32_hewehdr teirieVe class-dependertt object elf getehdr(3E) 

/elf32_getphdr^ elf32^ti6Wphdr retrieve class-dependent prog^ratii/ elf_getphdr(3E) 

header elf_^etshdf: elfi^jgetshdl: retrieve clai^dependent secfion ..w....; elf_getshdr(3E) 

elf getideht retrieve file identification data elf_getident<3E) 

contents elf_ravvfile retrieve uninterpreted file w...........v............ elf_rawfile(3E) 

abs, labs return integer absolute value abs(3Q 

name b^sename return the last element of a path basename(3G) 

type elfjsize: dfSljsize jretum the size of an object file elf_fsize(3E) 

getettv return vMue for environment ftame getenv(3C) 

sl^t d^a returned by stat sj^tent call stat(5) 

pointer in a stream fseek, rewind, ftell r^positibh ^ fil^ fseek(3S) 

/opendir, readdir, telldir, seekdir, rewinddk^ d^edir dirieiGldry/ .......v.v.i.......v.......;.v.i... directory(^C) 
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creat create a new file or rewrite an existing one creat(2) 

/copysign, fmod, fmodf, fabs, fabsf, rint, remainder floor, ceiling,/ floor (3M) 

file rmdel remove a delta from an SCCS nndel(l) 

rmdir remove a directory rmdir(2) 

in a path mkdirp, rmdirp create, remove directories rrJ^dirp(3G) 

chroot change root directory chroot(2) 

logarithm, power, square root functions /sqrtf exponential, exp(3M) 

atexit add program termination routine atexit(3C) 

expression compile and match routines /step, advance regular regexp(5) 

expression compile and match routines /step, advance regular regexpr(3G) 

editing activity sact print current SCCS file sact(l) 

allocation brk, sbrk change data segment space brk(2) 

logb, modf, modff, nextafter, scalb manipulate parts of/ /Idexp, frexp(3C) 

formatted input scanf, fscanf, sscanf convert scanf (3S) 

for help with message numbers or SCCS commands help ask help(l) 

cdc change the delta comment of an SCCS delta cdc(l) 

comb combine SCCS deltas comb(l) 

delta make a delta (change) to an SCCS file delta(l) 

sact print current SCCS file editing activity sact(l) 

get get a version of an SCCS file get(l) 

prs print an SCCS file prs(l) 

rmdel remove a delta from an SCCS file rmdel(l) 

sccsdiff compare two versions of an SCCS file sccsdiff(l) 

sccsfile format of SCCS file sccsfile(4) 

imget imdo a previous get of an SCCS file imget(l) 

val validate an SCCS file val(l) 

admin create and administer SCCS files admin(l) 

SCCS file sccsdiff compare two versions of an sccsdiff(l) 

sccsfile format of SCCS file sccsfile(4) 

sdb symbolic debugger sdb(l) 

bsearch binary search a sorted table bsearch(3C) 

Isearch, Ifind linear search and update lsearch(3C) 

directories pathfind search for named file in named pathfind(3G) 

hcreate, hdestroy manage hash search tables hsearch, hsearch(3C) 

tfind, tdelete, twalk manage binary search trees tsearch, tsearch(3Q 

elf_newdata, elfjrawdata get section data elf_getdata, elf_getdata(3E) 

retrieve class-dependent section header /elf32_getshdr elf_getshdr(3E) 

elf_newscn, elf nextscn get section information /elf ndxscn, elf_getscn(3E) 

mcs manipulate the comment section of an object file mcs(l) 

files size print section sizes in bytes of object , size(l) 

/nrand48, mrand48, jrand48, srand48, seed48, lcong48 generate imifonnly/ drand48(3C) 

/opendir, readdir, telldir, seekdir, rewinddir, dosedir/ directory(3C) 

shmget get shared memory segment identifier shmget(2) 

brk, sbrk change data segment space allocation brk(2) 

dump diunp selected parts of an object file dvimp(l) 

semctl semaphore control operations semctl(2) 

semop semaphore operations semop(2) 
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semget get set of semaphores semget(2) 

semctl semaphore control operations semctl(2) 

semget get set of semaphores semget(2) 

semop semaphore operations semop(2) 

putmsg send a message on a stream putmsg(2) 

group of processes kill send a signal to a process or a kill(2) 

raise send signal to program raise(3Q 

elfjnext sequential archive member access elf_next(3E) 

alarm set a process alarm dock alarm (2) 

umask set and get file creation mask umask(2) 

asdi map of ASCII character set ascii(5) 

ffs find first set bit ffs(3C) 

timezone set default system time zone timezone(4) 

times utime set file access and modification utime(2) 

elfjill set fiU byte elf_fill(3E) 

semget get set of semaphores semget(2) 

setpgrp set process group ID setpgrp(2) 

stime set time stime(2) 

setuid, setgid set user and group IDs setuid(2) 

ulimit get and set user limits ulimit(2) 

a stream setbuf, setvbuf assign buffering to setbuf(3S) 

setuid, setgid set user and group IDs setuid(2) 

getgrent getgrgid, getgrnam, setgrent, endgrent, fgetgrent get/ getgrent(3Q 

setjmp, longjmp non-local goto setjmp(3C) 

crypt, setkey, encrypt generate encryption crypt(3C) 

program's locale setlocale modify and query a setlocale(3C) 

setpgrp set process group ID setpgrp(2) 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent/ getpwent(3C) 

IDs setuid, setgid set user and group setuid(2) 

/getutid, getutline, pututline, setutent, endutent, utmpname access/ getut(3Q 

stream setbuf, setvbuf assign buffering to a setbuf(3S) 

for/ addseverity build a list of severity levels for an application addseverity(3Q 

machine-independent fashion sputl, sgetl access long integer data in a sputl(3X) 

shmctl shared memory control operations shmctl(2) 

shmop shared memory operations shmop(2) 

shmget get shared memory segment identifier shmget(2) 

system issue a shell command system(3S) 

gmatch shell global pattern matching gmatch(3G) 

operations shmcti shared memory control shmctl(2) 

identifier shmget get shared memory segment shmget(2) 

shmop shared memory operations shmop(2) 

sigpause signal management sigset, sighold, sigrelse, sigignore, sigset(2) 

sigset, sighold, sigrelse, sigignore, sigpause signal/ sigset(2) 

generate an abnormal termination signal abort abort(3C) 

sigrelse, sigignore, sigpause signal management sigset, sighold, sigset(2) 

pause suspend process imtil signal pause(2) 

what to do upon receipt of a signal signal specify signal(2) 
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receipt of a sign^ signal specify what to do iipm signal(2) 

processes kill send a signal to a process or a group of kill(2) 

raise send signal to pro^^ raise(3C) 

ssignal, gsignal software signals ssignal(3Q 

sighold, sigrelse, sigignore, sigpause signal management sigset, sigset(2) 

signal management sigset, sighold, sigrelse, sigignore, sigpause sigset(2) 

sigignore, sigpause signal/ sigset, sighold, sigrelse, sigset(2) 

lex generate programs for simple lexical tasks lex(l) 

rand, srand simple random-nimiber generator rand(3C) 

asin, asinf, acos, acosf,/ trig: sin, sinf, cos, cosf, tan, tanf, trig(3M) 

asinf, acos, acosf,/ trig: sin, sinf, cos, cosf, tan, tanf, asin, trig(3M) 

tanh, tanhf, asinh, acosh,/ sinh, sinhf, cosh, coshf, , sinh(3M) 

tanhf, asinh, acosh,/ sinh, sinhf, cosh, coshf, tanh, sinh(3M) 

elf_fsize: elf32_fsi2e return the size of an object file type elf_fsize(3E) 

of object files size print section sizes in bytes size(l) 

size print section sizes in bytes of object files size(l) 

interval sleep suspjend execution for sleep(3Q 

current user ttyslot find the slot in the utmp file of the ttyslot(3C) 

ssignal, gsignal software signals ssignal(3Q 

qsort quicker sort qsort(3C) 

tsort topological sort tsort(l) 

bsearch binary search a sorted table bsearch(3C) 

brk, sbrk change data segment space allocation brk(2) 

mknod make a directory, or a special or ordinary file mknod(2) 

strftime language specific strings strftime(4) 

a signal signal specify what to do upon receipt of signal(2) 

bufsplit split buffer into fields bufsplit(3G) 

printf, fprintf, sprintf print formatted output printf(3S) 

data in a machine-independent/ sputl, sgetl access long integer sputl(3X) 

/logf, loglO, loglQf, pow, powf, sqrt, sqrtf exponential, logarithm,/ exp(3M) 

/loglO, loglOf, pow, powf, sqrt, sqrtf exponential, logarithm,/ exp(3M) 

exponential, logarithm, power, square root functions /sqrt, sqrtf exp(3M) 

generator rand, srand simple random-number rand<3C) 

/lrand48, nrand4S, mrand48, jrand48, srand48, se€d48, lcong48 generate/ ........................... drand48(3C) 

scanf, fscanf, sscanf convert formatted input scanf(3S) 

ssignal, gsignal software signals ssignal(3Q 

package stdio standard buffered input/output stdio(3S) 

package stdipc: ftok standard interprocess communication stdipc(3Q 

call Stat data returned by Stat System stat(5) 

Stat, fstat get file status stat(2) 

Stat data returned by stat system call stat(5) 

information staffs, fstatfs get file system statfs(2) 

ustat get file system statistics ustat(2) 

feof, clearerr, fileno stream status inquiries ferror, ferror(3S) 

Stat fstat get file status stat(2) 

list stdarg handle variable argument stdarg(5) 

fmtmsg display a message on stderr or syst^ oonsole fmtmsg(3C) 
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input/output package stdio standard buffered stdio(3S) 

commiuucation package stdipc: ftok standard interprocess stdipc(3C) 

compile and match/ regexp: compile, step, advance regular expression regexp(5) 

compile and/ regexpr: compile, step, advance regular expression regexpr(3G) 

slime set time stime(2) 

wait wait for child process to stop or terminate wait(2) 

string manipulations str: strfind, strrspn, strtms str(3G) 

compressing or/ strccpy: streadd, strcadd, strecpy copy strings, strccpy(3G) 

strncmp, strcpy, stmcpy,/ string: strcat, strdup, stmcat, strcmp, string(3Q 

copy strings, compressing or/ strccpy: streadd, strcadd, strecpy strccpy(3G) 

/stnicmp, strcpy, stmcpy, strlen, stichr, sb rclu", strpbrk, strspn,/ string(30 

string: strcat, strdup, stmcat, strcmp, strncmp, stixpy, stmcpy,/ string(3Q 

strcoll string coUation strcoll(3Q 

/strdup, strncat, strcmp, stmcmp, strcpy, stmcpy, strlen, strchr,/ string(3Q 

/strchr, strrchr, strpbrk, strspn, strcspn, strtok, strstr string/ string(3Q 

strcpy, strncpy,/ string: strcat, strdup, stmcat, stianp, stmcmp, string(3Q 

stiings, compressing or/ strccpy: streadd, strcadd, strecpy copy strccpy(3G) 

fclose, fflush close or flush a stream fclose(3S) 

fopen, freopen, fdopen open a stream fop>en(3S) 

reposition a file pointer in a stream fseek, rewind, f tell fseek(3S) 

reposition a file pointer in a stream fsetpos, fgetpos fsetpos(3Q 

getw get character or word from a stream getc, getchar, fgetc, getc(3S) 

getmsg get next message off a stream , getmsg(2) 

gets, fgets get a string from a stream gets(3S) 

putw put character or word on a stream putc, putdiar, fputc, , putc(3S) 

putmsg send a message on a stieam putmsg(2) 

puts, fputs put a string on a stream puts(3S) 

sefvbuf assign buffering to a stream setbuf, , setbuf(3S) 

f error, feof, clearerr, fileno stream status inquiries ferror(3S) 

push character back onto input stream imgetc ungetc(3S) 

bgets read stream up to next delimiter bgets(3G) 

poll STREAMS input/output multiplexing poll(2) 

or/ strccpy: streadd, strcadd, strecpy copy strings, compressing strccpy(3G) 

strerror get error message string strerror(3Q 

manipulations str: strfind, strrspn, strtms string str(3G) 

date and time to string strftime, cftime, ascftime, convert strf time(3Q 

strftime language specific strings strftime(4) 

long integer and base-64 ASQI string a641, 164a convert between a641(3Q 

strcoll stiing collation strcoll(3Q 

tzset convert date and time to string /localtime, gmtime, asctime, ctime(3C) 

convert floating-point number to string ecvt, fcvt, gcvt ecvt(3C) 

gets, fgets get a string from a stream gets(3S) 

mbstowcs, wcstombs multibyte string functions mbstring: mbsb"ing(3Q 

getsubopt parse suboptions from a string , getsubopt(30 

str: strfind, strrspn, strtms string manipulations str(3G) 

puts, fputs put a string on a stream puts(3S) 

strspn, strcspn, strtok, strstr string operations /strpbrk, string(3Q 
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elf_strptr make a string pointer elf_strptr(3E) 

strcmp, stmcmp, strcpy, stmcpy,/ string: strcat, strdup, stmcat, string(3C) 

strerror get error message string strerror(30 

ascftime, convert date and time to string strftime, cftime, strftime(3C) 

strtod, atof, convert string to double-precision number strtod(3C) 

strtol, strtoul, atol, atoi convert string to integer strtol(3C) 

strxfrm string transformation strxfrm(3C) 

/streadd, strcadd, strecpy copy strings, compressing or expanding/ strccpy(3G) 

strftime language specific strings strftime(4) 

what print identification strings what(l) 

and line number information from/ strip strip symbol table, debugging strip(l) 

line number information from/ strip strip symbol table, debugging and strip(l) 

/strcmp, stmcmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk,/ string(3C) 

stmcpy,/ string: strcat, strdup, stmcat, strcmp, stmcmp, strcpy, string(3C) 

/strcat, strdup, strncat, strcmp, stmcmp, strcpy, stmcpy, strlen,/ string(3C) 

/stmcat, strcmp, stmcmp, strcpy, stmcpy, strlen, strchr, strrchr,/ string(3C) 

/stmcpy, strlen, strchr, strrdu*, strpbrk, strspn, strcspn, strtok,/ string(3C) 

/strcpy, stmcpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn,/ string(3C) 

manipulations str: strfind, strrspn, strtms string str(3G) 

/strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strstr/ string(3C) 

strpbrk, strspn, strcspn, strtok, strstr string operations /strrchr, string(3C) 

double-precision number strtod, atof, convert string to strtod(3C) 

/strrchr, strpbrk, strspn, strcspn, strtok, strstr string operations string(3C) 

string to integer strtol, strtoul, atol, atoi convert strtol(3C) 

to integer strtol, strtoul, atol, atoi convert string strtol(3C) 

str: strfind, strrspn, strtms string manipulations str(3G) 

offsetof offset of structure member offsetof(3C) 

mktime converts a tm structure to a calendar time mktime(3Q 

strxfrm string transformation strxfrm(3C) 

getsubopt parse suboptions from a string getsubopt(3C) 

sync update super block s)nic(2) 

sleep suspend execution for interval sleep(3Q 

pause suspend process imtil signal pause(2) 

swab swap bytes swab(3Q 

swab swap bytes swab(3Q 

number information/ strip strip symbol table, debugging and line strip(l) 

elf_getarsym retrieve archive symbol table elf jgetarsym(3E) 

sdb symbolic debugger sdb(l) 

sync update super block S)mc(2) 

information sysfs get file system type sysfs(2) 

Stat data retumed by stat system call stat(5) 

intro introduction to system calls and error nvimbers intro(2) 

display a message on stderr or system console fmtmsg fmtmsg(3C) 

types primitive system data types types(5) 

perror print system error messages perror(3Q 

directory entries and put in a file system independent format /read getdents(2) 

statfs, fstatfs get file system information statfs(2) 
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system issue a shell command system(3S) 

mount mount a file system mount(2) 

ustat get file system statistics ustat(2) 

timezone set default system time zone timezone(4) 

sysfs get file system type information sysfs(2) 

umount unmount a fQe system umount(2) 

uname get name of current UNIX system vmame(2) 

bsearch binary search a sorted table bsearch(3C) 

information/ strip strip symbol table, debugging and line number strip(l) 

retrieve archive symbol table elf_getarsym elf_getarsym(3E) 

dass-dependent program header table /elf32_newphdr retrieve elf_getphdr(3E) 

classification and conversion tables chrtbl generate character chrtbl(lM) 

hdestroy manage hash search tables hsearch, hcreate, hsearch(3C) 

acosf,/ trig: sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, trig(3M) 

trig: sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, acosf,/ trig(3M) 

sinh, sinhf, cosh, coshf, tanh, tanhf, asinh, acosh,/ sinh(3M) 

/sinhf, cosh, coshf, tanh, tanhf, asinh, acosh, atanh/ sinh(3M) 

programs for simple lexical tasks lex generate lex(l) 

trees tsearch, tfind, tdelete, twalk manage binary search tsearch(3C) 

directory: opendir, readdir, telldir, seekdir, rewinddir,/ directory (3C) 

temporary file tmpnam, tempnam create a name for a tmpnam(3S) 

tmpfile create a temporary file tmpfile(3S) 

tmpnam, tempnam create a name for a temporary file tmpnam (3S) 

ctermid generate fQe name for terminal ctennid(3S) 

libwindows windowing terminal function library libwindows(3X) 

jagent host control of windowing terminal jagent(5) 

dial establish, an out-going terminal line connection dial(3Q 

ttyname, isatty find name of a terminal ttyname(3C) 

used between host and windowing terminal under layers(l) /protocol layers(5) 

exit, exit terminate process exit(2) 

wait for child process to stop or terminate wait wait(2) 

atexit add program termination routine atexit(3Q 

abort generate an abnormal termination signal abort(3C) 

plock lock process, text, or data in memory plock(2) 

search trees tsearch, tfind, tdelete, twalk manage binary tsearch(3C) 

the difference between two calendar times difftime computes difftime(3Q 

times times get process and child process times(2) 

times get process and child process times times(2) 

set file access and modification times utime utime(2) 

zone timezone set default system time timezone(4) 

mktime converts a tm structure to a calendar time mktime(3C) 

tmpfile create a temporary file tmpfile(3S) 

temporary file tmpnam, tempnam create a name for a tmpnam (3S) 

/tolower, _toupper, _tolower, toasdi translate characters conv(3C) 

popen, pdose initiate pipe to/from a process popen(3S) 

conv: toupper, tolower, _toupper, _tolower, toasdi translate/ conv(3C) 

toasdi translate/ conv: toupper, tolower, Joupper, _tolower, conv(3C) 
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tsOrt topological sort tsort(l) 

translate/ conv: toupper, tolower, toupper, _tolower, toasdi conv(3Q 

_tolower, toasdi translate/ conv: toupper, tolower, _toupper, conv(3Q 

ptrace process trace ptrace(2) 

strxfrm string transformation strxfrm(3C) 

toupper, _tolower, toasdi translate characters /tolower, conv(3Q 

cof2elf COFF to ELF object file translation cof2elf(l) 

elf32__xlatetom class-dependent data translation /elf32_xlatetot elf_xlate(3E) 

ftw walk ia file tree ftw(3Q 

tdelete, twalk manage binary search trees tsearch, tfind, tsearch(3Q 

tanf, asin, asint acos, acosf,/ trig: sin, sinf, cos, cosf, tan, trig(3M) 

acosf, atan, atanf, atan2, atgin2f trigonometric functions /acos, trig(3M) 

manage binary search trees tsearch, tfind, tdelete, twalk tsearch(3Q 

tsort topological sort tsort(l) 

terminal ttyname, isatty find name of a ttyname(3C) 

file of the current user ttyslot find the slot in the utmp ttyslot(3C) 

tsearch, tfind, tdelete, twalk manage binary search trees tsearch(3Q 

return the size of an object file type elf_fsize: elf32_fsize elf_fsize(3E) 

elfjcind determine file type elf_kind(3E) 

sysfs get file system type information sysfs(2) 

/fpdass, imordered determine type of floating-point number isnan(3C) 

types primitive system data types types(5) 

types primitive system data types types(5) 

ctime, localtime, gmtime, asctime, tzset convert date and time to/ ctime(3C) 

uadmin administrative control uadmin(2) 

getpw get name from UID getpw(3Q 

ulimit get and set user limits ulimit(2) 

mask umask set and get file creation umask(2) 

imiovmt unmount a file system umoimt(2) 

system vmame get name of current UNIX vmame(2) 

imget imdo a previous get of an SGCS file vmget(l) 

sees file vmget undo a previous get of an unget(l) 

input stream ungetc push character back onto ungetc(3S) 

/srand48, seed48, lcong48 generate imiformly distributed pseudo-random/ drand48(3C) 

elf^rawfile retrieve uninterpreted file contents elf_rawfile(3E) 

mktemp make a unique file name mktemp(3C) 

uname get name of current UNIX system imame(2) 

imliidc remove directory entry vmlink(2) 

umoimt unmoimt a file system umoimt(2) 

isnand, isnanf, finite, fpclass, imordered determine type of/ isnan, isnan(3C) 

pause suspend process until signal pause(2) 

elf update update an descriptor elf_update(3E) 

programs make maintain, update, and regenerate groups of make(l) 

Isearch, Ifind linear search and update lsearch(3C) 

sync update super block sync(2) 

signal specify what to do upon receipt of a signal signal(2) 

levels for an application for use with fmtmsg /a list of severity addseverity(3Q 
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setuid, setgid set user and group IDs setuid(2) 

get character login name of the user cuserid cuserid(3S) 

/geteuid, getgid, getegid get real user, effective user, real group,/ getuid(2) 

environ user environment environ(5) 

ulimit get and set user limits ulimit(2) 

/getegid get real user, effective user, real group, and effective/ getuid(2) 

in the utmp file of the current user ttyslot find the slot ttyslot(3C) 

maillock manage lockfile for user's mailbox maillock(3X) 

elf end finish using an object file elf_end(3E) 

ustat get file system statistics ustat(2) 

modification times utime set file access and utime(2) 

utmp, wtmp utmp and wtmp entry formats utmp(4) 

setutent, endutent, utmpname access utmp file entry /pututline, getut(3Q 

ttyslot find itie slot in the utmp file of the current user ttyslot(3C) 

formats utmp, wtmp utmp and wtmp entry utmp(4) 

/pututline, setutent, endutent, utmpname access utmp file entry getut(3Q 

val validate an SCCS file val(l) 

val validate an SCCS file val(l) 

abs, labs retimt integer absolute value abs(3Q 

elf hash compute hash value elf_hash(3E) 

getenv return value for environment name , getenv(3C) 

floor, ceiling, remainder, absolute value functions /rint, remainder floor(3M) 

putenv change or add value to environment putenv(3C) 

values machine-dependent values values(5) 

values machine-dependent values values(5) 

list varargs handle variable argument varargs(5) 

stdarg handle variable argument list stdarg(5) 

varargs handle variable argument list , varargs(5) 

print formatted output of a variable argimient list /vsprintf vprintf(3S) 

vc version control vc(l) 

get option letter from argument vector getopt getopt(3C) 

assert verify program assertion assert(3X) 

vc version control , vc(l) 

get get a version of an SCCS file get(l) 

coordinate library and application versions elf_version elf_version(3E) 

sccsdiff compare two versions of an SCCS file sccsdiff(l) 

output of a variable/ vprintf, vfprintf, vsprintf print formatted vprintf(3S) 

formatted output of a variable/ vprintf, vfprintf, vsprintf print vprintf(3S) 

a variable/ vprintf, vfprintf, vsprintf print formatted output of vprintf(3S) 

terminate wait wait for child process to stop or wait(2) 

or terminate wait wait for diild process to stop wait(2) 

ftw walk a file tree ftw(3C) 

mbstring: mbstowcs, wcstombs multibyte string functions mbstring(3C) 

mbchar: mbtowc, mblen, wctomb multibyte character handling mbchar(3C) 

encrypted isencrypt determine whether a character buffer is isencr)rpt(3G) 

libwindows windowing terminal function library libwindows(3X) 

jagent host control of windowing terminal jagent(5) 
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/protocol used between host 2ind windowing terminal under layers(l) layers(5) 

prof profile within a function prof (5) 

fgetc, getw get character or word from a stream getc, getchar, getc(3S) 

fputc, putw put character or word on a stream putc, putchar, putc(3S) 

chdir change working directory chdir(2) 

getcwd get pathname of current working directory i getcwd(3Q 

write write on a file write(2) 

putpwent write password file entry putpwent(3C) 

write write on a file write(2) 

open open for reading or writing open(2) 

utmp, wtmp utmp and wtmp entry formats utmp(4) 

utmp, wtmp utmp and wtmp entry formats utmp(4) 

channels protocol used by xt driver xtproto multiplexed xtproto(5) 

protocol used by xt driver xtproto multiplexed channels xtproto(5) 

bessel: jO, ]i, jn, yO^ yl^ yn Bessel functions bessel(3M) 

bessel: jO, jl, jn, yO, yl, yn Bessel functions bessel(3M) 

yacc yet another compiler-compiler yacc(l) 

yacc yet another compiler-compiler yacc(l) 

bessel: jO, jl, jn, yO, yl, yn Bessel functions bessel(3M) 

timezone set default system time zone timezone(4) 
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NAME 

intro - introduction to programming commands 
DESCRIPTION 

This section describes the programming commands in alphabetical order. Unless 
otherwise noted, the commands accept options and other arguments according to 
the following syntax: 

name [option(s)] Icmdargis)] 

where: 

name is the name of an executable file. 

option is -noarglelter{s) or -^rgletter <> optarg, where: 

noargletter is a single letter representing an option without an 
option argument; 

argletter is a single letter representing an option requiring an option 
argument; 

<> is optional white space; 

optarg is an option argument (character string) satisfying the 
preceding argletter. 

cmdarg is by itself, which indicates the standard input, or a path name 

(or other command argument) not beginning with 

Throughout the manual pages there are references to TMPDIR, BINDIR, INCDIR, 
and LIBDIR. These represent directory names whose value is specified on each 
manual page as necessary. For example, TMPDIR might refer to /usr/tirp. 
These are not environment variables and cannot be set. [There is an environment 
variable called TMPDIR which can be set. See t:irpnam(3S).] There are also refer- 
ences to LIBPATH, the default search path of the link editor and other tools. 

SEE ALSO 

exit(2), wait(2), getopt(3C). 
getopts(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon termination, each command returns two bytes of status, one supplied by 
the system and giving the cause for termination, and (in the case of "normal" ter- 
mination) one supplied by the program [see wait(2) and exit (2)]. The former 
byte is 0 for normal termination; the latter is customarily 0 for successful execu- 
tion and non-zero to indicate troubles such as erroneous parameters, or bad or 
inaccessible data. It is called variously "exit code," "exit status," or "return 
code," and is described only where special conventions are involved. 

NOTES 

Some commands produce unexpected results when processing files containing 
null characters. These commands often treat text input lines as strings and there- 
fore become confused upon encoimtering a null character (the string terminator) 
within a line. 
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NAME 

admin - create and administer SCCS files 
SYNOPSIS 

admin [-n] [-ilname]] [-rrel] l-t[name]] l-fflagiflag-val]] [-6flag[flag-val]] l-alogin] 
[-elogin] [-toltnrlist]] [-ylcomment]] [-h] [-z] files 

DESCRIPTION 

admin is used to create new SCCS files and change parameters of existing ones. 
Arguments to admin, which may appear in any order, consist of keyletter argu- 
ments (that begin with -) and named files (note that SCCS file names must begin 
with the characters s . ). If a named file does not exist, it is created and its param- 
eters are initialized according to the specified keyletter arguments. Parameters 
not initialized by a keyletter argument are assigned a default value. If a named 
file does exist, parameters corresponding to specified keyletter argtiments are 
changed, and other parameters are left unchanged. 

If a directory is named, admin behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and unreadable files are silently ignored. If a 
name of - is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed. Again, non-SCCS files and 
unreadable files are silently ignored. 

The keyletter arguments are listed below. Each argument is explained as if only 
one named file were to be processed because the effect of each argument applies 
independently to each named file. 

-n This keyletter indicates that a new SCCS file is to be created. 

-iiname] The name of a file from which the text for a new SCCS file is to be 
taken. The text constitutes the first delta of the file (see -r 
keyletter for delta numbering scheme). If the -i keyletter is used, 
but the file name is omitted, the text is obtained by reading the 
standard input until an end-of-file is encountered. If this keyletter 
is omitted, then the SCCS file is created empty. Only one SCCS file 
may be created by an admin command on which the i keyletter is 
supplied. Using a single admin to create two or more SCCS files 
requires that they be created empty (no -i keyletter). Note that 
the -i keyletter implies the -n keyletter. 

-rrel The release into which the initial delta is inserted. This keyletter 

may be used only if the -i keyletter is also used. If the -r 
keyletter is not used, the initial delta is inserted into release 1. 
The level of the initial delta is always 1 (by default initial deltas 
are named 1.1). 

-tlname] The name of a file from which descriptive text for the SCCS file is 
to be taken. If the -t keyletter is used and admin is creating a 
new SCCS file (the -n and /or -i keyletters also used), the descrip- 
tive text file name must also be supplied. In the case of existing 
SCCS files: (1) a ~t keyletter without a file name causes removal 
of the descriptive text (if any) that is currently in the SCCS file, 
and (2) a -t keyletter with a file name causes text (if any) in the 
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named file to replace the descriptive text (if any) that is currently 
in the SCCS file. 

-fflag This keyletter specifies a flag, and, possibly, a value for the flag, to 

be placed in the SCCS file. Several -f keyletters may be supplied 
on a single admin command line. The allowable flags and their 
values are: 

b Allows use of the -b keyletter on a get command to create 

branch deltas. 

cceil Tlie highest release (i.e., ceiling): a number greater than 0 

but less than or equal to 9999 that may be retrieved by a get 
command for editing. The default value for an unspecified c 
flag is 9999. 

ffloor The lowest release (i.e., floor): a number greater than 0 but 

less than 9999 that may be retrieved by a get command for 
editing. The default value for an tmspecified f flag is 1. 

dSID The default delta number (SID) to be used by a get com- 

mand, 

i[str] Causes the No id keywords (ge6) message issued by get 

or delta to be treated as a fatal error. In the absence of this 
flag, the message is only a warning. The message is issued if 
no SCCS identification keywords [see get(l)] are found in the 
text retrieved or stored in the SCCS file. If a value is sup- 
plied, the keywords must exactly match the given string. 
The string must contain a keyword, and no embedded new- 
lines. 

j Allows concurrent get commands for editing on the same 

SID of an SCCS file, lliis flag allows multiple concurrent 
updates to the same version of the SCCS file. 

llist A list of releases to which deltas can no longer be made (get 

-e against one of these "locked" releases fails). The list has 
the following syntax: 

<list> ::=r <range> I <list> , <range> 
<range> RELEASE NUMBER I a 

The character a in the list is equivalent to specifying all 
releases for the named SCCS file. 

n Causes delta to create a null delta in each of those releases 

(if any) being skipped when a delta is made in a new release 
(e g., in making delta 5.1 after delta 2.7, releases 3 and 4 are 
skipped). These null deltas serve as anchor points so that 
branch deltas may later be created from them. The absence 
of this flag causes skipped releases to be non-existent in the 
SCCS file, preventing branch deltas from being created from 
them in the future. 
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qtext User-definable text substituted for all occurrences of the %Q% 

keyword in SCCS file text retrieved by get. 

Tcmod module name of the SCCS file substituted for all occurrences 

of the %M% keyword in SCCS file text retrieved by get. If the 
m flag is not specified, the value assigned is iha name ol the 
SCCS file with the leading s . removed. 

ttype iy})e of module In the SCCS file substituted for all occurrences 

of %Y% keyword in SCCS file text retrieved by gat. 

vipgm] Causes delta to prompt for Modification Ret|U£ist (MR) 
numbers as the reason for creating a delta. The optional 
value specifies tlie name of an MR number validity checking 
program [see delta(l)]. This program will receive as argu- 
ments the module name, tlie value of the type flag (see ttype 
above), and the ntrlist. (If this flag is set when creating an 
SCCS file, the m keyletter must also be used even If its value 
is null). 

-6flag Causes removal (deletion) of the specified flag from an SCCS file. 

The -d keyletter may be specified only when processing existing 
SCCS files. Sc^veral -d keyletters may be supplied in a slrjgle 
admin command. See the -f keyletter for allowable flag names. 

iXlist used with -d indicates a list of releases to be unlocked. See 
the ~f keyletter for a description of the i flag and the syntax of a 
list,) 

-alogin A login name, or numerical UNIX System group ID, to be added to 
the list of users who may make deltas (changes) to the SCCS file. 
A group ID is equivalent to specifying all login names common to 
that group ID. Several a keyletters may be used on a single admn 
command line. As many logins or numerical group IDs as desired 
may be on the list simultaneously. If the list of users is empty, 
then anyone may add deltas. If login or group ID is preceded by 
a ! they are to be denied permission to make deltas. 

-elogin A login name, or numerical group to be erased from the list of 
users allowed to make deltas (changes) to the SCCS file. Specify- 
ing a group ID is equivalent to specifying all login names com- 
mon to that group ID. Several keyletters may be used on a sin- 
gle admin command line. 

-ittmriist] The list of Modification Requests (MR) numbers is inserted into 
the SCCS file as the reason for creating the initial delta in a 
manner identical to delta. The v flag must be set and the MR 
numbers are validated if the v flag has a value (the name of an MR 
number validation program). Diagnostics will occur if the v flag 
is not set or MR validation fails. 

-y[comment] The comment text is inserted into the SCCS file as a comment for 
the initial delta in a manner identical to that of delta. Omission 
of the -y kejtoter results in a default comment line being 
inserted. 
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The -y keyletter is valid only if the -i and /or -n keyletters are 
specified (i.e., a new SCCS file is being created). 

-h Causes admin to check the structure of the SCCS file [see 

sccsf ile(4)], and to compare a newly computed check-sim\ (the 
sum of all the characters in the SCCS file except those in the first 
line) with the check-sum that is stored in the first line of the SCCS 
file. Appropriate error diagnostics are produced. This keyletter 
inhibits writing to the file, nullifying the effect of any other 
keyletters supplied; therefore, it is only meaningful when process- 
ing existing files. 

-z The SCCS file check-sum is recomputed and stored in the first line 

of the SCCS file (see -h, above). Note that use of this keyletter on 
a truly corrupted file may prevent future detection of the corrup- 
tion. 

The last component of all SCCS file names must be of the form s .file. New SCCS 
files are given mode 444 [see chmodd)]. Write permission in the pertinent direc- 
tory is, of course, required to create a file. All writing done by admin is to a tem- 
porary x-file, called K.file, [see get(l)], created with mode 444 if the admin com- 
mand is creating a new SCCS file, or with the same mode as the SCCS file if it 
exists. After successful execution of admin, the SCCS file is removed (if it exists), 
and the x-file is renamed with the name of the SCCS file. This renaming process 
ensures that changes are made to the SCCS file only if no errors occurred. 

It is recommended that directories containing SCCS files be mode 755 and that 
SCCS files themselves be mode 444. The mode of the directories allows only the 
owner to modify SCCS files contained in the directories. The mode of the SCCS 
files prevents any modification at all except by SCCS commands. 

admin also makes use of a transient lock file (called z.fileX which is used to 
prevent simultaneous updates to the SCCS file by different users. See get(l) for 
further information. 

FILES 

x-file [see delta(l)] 

z-file [see delta(l)] 

bdiff Program to compute differences between the "gotten" file and 

the g-file [see get(l)]. 

SEE ALSO 

bdif f (1), ed(l), delta(l), get(l), help(l), prs(l), what(l), sccsf ile(4). 

DIAGNOSTICS 

Use the help command for explanations. 

NOTES 

If it is necessary to patch an SCCS file for any reason, the mode may be changed 
to 644 by the owner allowing use of a text editor. You must run admin -h on the 
edited file to check for corruption followed by an admin -z to generate a proper 
check-sum. Another admin -h is recommended to ensure the SCCS file is valid. 
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NAME 

ar ~ maintain portable archive or library 
SYNOPSIS 

ar[ -V] - key I arg ] [ posname ] afile [ name. . . ] 
DESCRIPTION 

The ar command maintains groups of files combined into a single archive file. 
Its main use is to create and update library files. However, it can be used for any 
similar purpose. The magic string and the file headers used by ar consist of 
printable ASQI characters. If an archive is composed of printable files, the entire 
archive is printable. 

When ar creates an archive, it creates headers in a format that is portable across 
all machines. The portable archive format and structure are described in detail in 
ar(4). The archive symbol table [described in ar(4)] is used by the link editor Id 
to effect multiple passes over libraries of object files in an efficient manner. An 
archive symbol table is only created and maintained by ar when there is at least 
one object file in the archive. The archive symbol table is in a specially named 
file that is always the first file in the archive. This file is never mentioned or 
accessible to the user. Whenever the ar command is used to create or update the 
contents of such an archive, the symbol table is rebuilt. The s option described 
below will force the symbol table to be rebuilt. 

The -V option causes ar to print its version number on standard error. 

Unlike command options, the key is a required part of the ar command line. The 
key is formed with one of the following letters: drqtpmx. Arguments to the key, 
alternatively, are made with one of more of the following set: vuaibcls. 
posname is an archive member name used as a reference point in positioning other 
files in the archive, afile is the archive file. The names are constituent files in the 
archive file. The meanings of the key characters are as follows: 

d Delete the named files from the archive file. 

r Replace the named files in the archive file. If the optional character u is 
used with r, then only those files with dates of modification later than the 
archive files are replaced. If an optional positioning character from the set 
abi is used, then the posname argument must be present and specifies that 
new files are to be placed after (a) or before (b or i) posname. Otherwise 
new files are placed at the end. 

q Quickly append the named files to the end of the archive file. Optional 
positioning characters are invalid. The command does not check whether 
the added members are already in the archive. This option is useful to 
avoid quadratic behavior when creating a large archive piece-by-piece. 

t Print a table of contents of the archive file. If no names are given, all files 
in the archive are listed. If names are given, only those files are listed. 

p Print the named files in the archive. 

m Move the named files to the end of the archive. If a positioning character 
is present, then the posname argument must be present and, as in r, 
specifies where the files are to be moved. 
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X Extract the named files. If no names are given, all files in the archive are 
extracted. In neither case does x alter the archive file. 

The meanings of the other key arguments are as follows: 

V Give a verbose file-by-file description of the making of a new archive file 
from the old archive and the constituent files. When used with t, give a 
long listing of all information about the files. When used with yi, print the 
filename preceding each extraction. 

c Suppress the message that is produced by default when afile is created. 

1 This option is obsolete. It is recognized, but ignored, and will be removed 
in the next release. 

s Force the regeneration of the archive symbol table even if ar(l) is not 
invoked with a command which will modify the archive contents. This 
command is useful to restore the archive symbol table after the strip(l) 
command has been used on the archive. 

SEE ALSO 

ld(l), lorderd), stripd), a.out(4), ar(4). 

NOTES 

If the same file is mentioned twice in an argument list, it may be put in the 
archive twice. 

Since the archiver no longer uses temporary files, the -1 option is obsolete and 
will be removed in the next release. 

By convention, archives are suffixed with the characters .a. 
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NAME 

as - assembler 

SYNOPSIS 

as [options] file 

DESCRIPTION 

The as command creates object files from assembly language source files. The 
following flags may be specified in any order: 

-o objfile Put the output of the assembly in objfile. By default, the output file 
name is formed by removing the . s suffix, if there is one, from the 
input file name and appending a . o suffix. 

-n Turn off long/ short address optimization. By default, address 

optimization takes place. 

-m Run the m4 macro processor on the input to the assembler. 

-R Remove (imlink) the input file after assembly is completed. 

-dl Obsolete. Assembler issues a warning saying that it is ignoring the 

-dl option. 

-T Accept obsolete assembler directives. 

-V Write the version number of the assembler being run on the stan- 

dard error output. 

-Q{y I n} If -Qy is specified, place the version number of the assembler being 
run in the object file. The default is -Qn. 

-Y lTaS],di^ Find the m4 preprocessor (m) and /or the file of predefined macros 
(d) in directory dir instead of in the customary place. 

FILES 

By default, as creates its temporary files in /usr/t:mp. This location can be 
changed by setting the environment variable TMPDIR [see tenpnam in tnpnainCSS)]. 

SEE ALSO 

cc(l), ld(l), in4(l), nind), strip(l), tmpnanOS), a.out(4). 

NOTES 

If the -m (in4 macro processor invocation) option is used, keywords for m4 [see 
m4(l)] cannot be used as symbols (variables, functions, labels) in the input file 
since m4 cannot determine which keywords are assembler symbols and which 
keywords are real m4 macros. 

The .align assembler directive may not work in the .text section when 
long/short address optimization is performed. 

Arithmetic expressions may only have one forward referenced symbol per expres- 
sion. 

Whenever possible, you should access the assembler through a compilation sys- 
tem interface program such as cc. 
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NAME 

cb - C program beautifier 
SYNOPSIS 

cb [-S] [-j] i-lleng] [-V] [file ...] 
DESCRIPTION 

The cb comand reads syntactically correct C programs either from its arguments 
or from the standard input, and writes them on the standard output with spacing 
and indentation that display the structure of the C code. By default, cb preserves 
all user new-lines. 

cb accepts the following options. 

-s Write the code in the style of Kemighan and Ritchie found in The C 

Programming Language. 

- j Put split lines back together. 

-1 leng Split lines that are longer than leng. 

-V Print on standard error output the version of cb invoked. 

NOTES 

cb treats asm as a ke5word. 

The format of structure initializations is tmchanged by cb. 

Punctuation that is hidden in preprocessing directives causes indentation errors. 

SEE ALSO 

cc(l). 

Kernighan, B. W., and Ritchie, D. M., The C Programming Language, Second Edi- 
tion, Prentice-Hall, 1988. 
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NAME 

cc - C compiler 

SYNOPSIS 

cc [options] file ... 

DESCRIPTION 

cc is the interface to the C compilation system. The compilation tools conceptu- 
ally consist of a preprocessor, compiler, optimizer, basic block analyzer, assem- 
bler, and link editor, cc processes the supplied options and then executes the 
various tools with the proper arguments, cc accepts several types of files as 
argimients. 

Files whose names end with . c are taken to be C source files and may be prepro- 
cessed, compiled, optimized, instrumented for profiling, assembled, and link 
edited. The compilation process may be stopped after the completion of any pass 
if the appropriate options are supplied. If the compilation process runs through 
the assembler, then an object file is produced whose name is that of the source 
with . o substituted for . c. However, the . o file is normally deleted if a single C 
file is compiled and then immediately link edited. In the same way, files whose 
names end in . s are taken to be assembly source files; they may be assembled 
and link edited. Files whose names end in .i are taken to be preprocessed C 
source files, and they may be compiled, optimized, instrumented for profiling, 
assembled, and link edited. Files whose names do not end in .c, .s, or .i are 
handed to the link editor, which produces an executable whose name by default 
is a . out. 

Since cc usually creates files in the current directory during the compilation pro- 
cess, it is necessary to run cc in a directory in which a file can be created. 

The following options are interpreted by cc: 

-A nante[ (tokens) ] 

Associates name as a predicate with the specified tokens as if by a tassert 
preprocessing directive. 

Preassertions: system (unix) 

cpu(i386) 
machine (1386) 

-A - Causes all predefined macros (other than those that begin with ) and 

predefined assertions to be forgotten. 

-C Cause the preprocessing phase to pass along all comments other than 
those on preprocessing directive lines. 

-c Suppress the link editing phase of the compilation and do not remove any 
produced object files. 

-D namel=tokens] 

Associates name with the specified tokens as if by a #def ine preprocessing 
directive. If no Hokens is specified, the token 1 is supplied. These 
predefinitions only exist under the -Xt and -Xa modes. 
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Predefinitions: 1386 
unix 

-E Only preprocess the named C files and send the result to the standard 
output. The output will contain preprocessing directives for use by the 
next pass of the compilation system. 

-f This option is obsolete and will be ignored. 

-g Cause the compiler to generate additional information needed for the use 
of sdb. Use of sdb on a program compiled with both the -g and -O 
options is not recommended unless the user understands the behavior of 
optimization. 

-H Print, one per line, the path name of each file included during the current 
compilation on the standard error output. 

-I dir Alter the search for included files whose names do not begin with / to 
look in dir prior to the usual directories. The directories for multiple -I 
options are searched in the order specified. 

-K PIC 

Causes position-independent code (PIC) to be generated. 

-L dir Add dir to the list of directories searched for libraries by Id. This option 
and its argument are passed to Id. 

-1 name 

Search the library libwam^.a. Its placement on the command line is 
significant as a library is searched at a point in time relative to the place- 
ment of other libraries and object files on the command line. This option 
and its argument are passed to Id. 

-O Arrange for compilation phase optimization. This option has no effiect on 
. s files. 

-o pathname 

Produce an output object file pathname, instead of the default a . out. This 
option and its argument are passed to Id. 

-P Only preprocess the named C files and leave the result in corresponding 
files suffixed . i. The output will not contain any preprocessing directives, 
unlike -E. 

-p Arrange for the compiler to produce code that counts the nimiber of times 
each routine is called; also, \i link editing takes place, profiled versions of 
libc.a and libm.a (with the -Im option) are linked. A mon.out file will 
then be produced at normal termination of execution of the object pro- 
gram. An execution profile can then be generated by use of prof. 

-Qc c can be either y or n. If c is y, identification information about each 
invoked compilation tool will be added to the output files (the default 
behavior). This can be useful for software administration. Giving n for c 
suppresses this information. 
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-q c c can be either 1 or p. -ql causes the invocation of the basic block 
analyzer and arranges for the production of code that counts the number 
of times each source line is executed. A listing of these counts can be gen- 
erated by use of Iprof . -qp is a synonym for -p. 

-S Compile, optimize (if -O is present), and do not assemble or link edit the 
named C files. The assembler-language output is left in corresponding 
files suffixed . s. 

-U name 

Causes any definition of name to be forgotten, as if by a #undef prepro- 
cessing directive. If the same name is specified for both -D and -U, name is 
not defined, regardless of the order of the options. 

-V Cause each invoked tool to print its version information on the standard 
error output. 

-V Cause the compiler to perform more and stricter semantic checks, and to 
enable certain lint-like checks on the named C files. 

-Mitool,arg^[,arg2 ...] 

Hand off the argimient(s) arg^ each as a separate argument to tool. Each 
argument must be separated from the preceding by only a comma. (A 
comma can be part of an argument by escaping it by an immediately 
preceding backslash (\) character; the backslash is removed from the 
resulting argument.) tool can be one of the following: 

p A synonym for 0 

0 compiler 
2 optimizer 

b basic block analyzer 
a assembler 

1 link editor 

For example, -}iia,-o,ohjfile passes -o and objfile to the assembler, in that 
order. 

The order in which the argument(s) are passed to a tool with respect to 
the other specified command line options may change. 

-X c Specify the degree of conformance to the ANSI C standard, c can be one 
of the following: 

t (transition) 

The compiled language includes all new features compatible with 
older (pre- ANSI) C (the default behavior). The compiler warns 
about all language constructs that have differing behavior between 
the new and old versions and uses the pre-ANSI C interpretation. 
This includes, for example, warning about the use of trigraphs the 
new escape sequence \a, and the changes to the integral promotion 
rules. 

a (ANSI) 

The compiled language includes all new features of ANSI C and 
uses the new interpretation of constructs with differing behavior. 
The compiler continues to warn about the integral promotion rule 
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FILES 



changes, but does not warn about trigraph replacements or new 
escape sequences. 

c (conformance) 

The compiled language and associated header files are ANSI C 
conforming, but include all conforming extensions of -Xa. Warn- 
ings will be produced about some of these. Also, only ANSI 
defined identifiers are visible in the standard header files. 

The predefined macro _J5TDC _ has the value 0 for -xt and -Xa, and 1 
for -Xc. All warning messages about differing behavior can be eliminated 
in -Xa through appropriate coding; for example, use of casts can eliminate 
the integral promotion change warnings. 

-Y item, dir 

Specify a new directory dir for the location of item, item can consist of any 
of the characters representing tools listed under the -W option or the fol- 
lowing characters representing directories containing special files: 

I directory searched last for include files: INCDIR (see -I) 

S directory containing the start-up object files: LIBDIR 

L obsolete. Use -YP instead. For this release, -YL will be simulated 

using -YP. -YL will be removed in the next release, 
U obsolete. Use -YP instead. For this release, -YU will be simulated 

using -YP. -YU will be removed in the next release. 
P Change the default directories used for finding libraries, dir is a 

colon-separated path list. 

If the location of a tool is being specified, then the new path name for the 
tool will be dir f tool. If more than one -Y option is applied to any one 
item, then the last occurrence holds. 

cc recognizes -a, -tiv -o, -r, -s, -t, -u, and -z and passes these options and 
their arguments to Id. cc also passes any unrecognized options to Id without 
any diagnostic. 

When cc is put in a file prefixcc, the prefix will be recognized and used to prefix 
the names of each tool executed. For example, OLDcc will execute OLDaconp, 
OLDoptinv OLDbasicblk, OLDas, and OLDld, and will link the object file(s) with 
OLDcrtl . o. Therefore, be careful when moving cc around. The prefix applies to 
the compiler, optimizer, basic block analyzer, assembler, link editor, and the 
start-up routines. 

file.c C source file 

fiie,i preprocessed C source file 

fik.o object file 

file. a assembly language file 

a. out link-edited output 

LIBDIR/^crti . o startup initialization code 

LIBDIR/ *crtl . o startup routine 
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L/BD7R/*crtn.o 

TMPDIR/* 

LIBDIR/acotap 

LIBDIR/optim 

LIBDIR/hasicblk 

BINDIR/as 

BINDIR/ld 

LIBDIR/liJoc.a 



last startup routine 
temporary files 
preprocessor and compiler 
optimizer 

basic block analyzer 
assembler 
link editor 
standard C library 



INCDIR 
LIBDIR 
BINDIR 
TMPDIR 



usually /usr/ include 
usually /usr/ccs/lib 
usually /usr/ocs/bin 



usually /usr/tinp but can be redefined by setting the 
environment variable TMPDIR (see textpnam in 
tnpnamOS)). 



SEE ALSO 



as(l), ld(l), lint(l), Iprof (1), prof (1), sdbdX monitor(3C), tirpnain(3S). 
The "C Compilation System" chapter in the Programmer's Guide: ANSI C and Pro- 
gramming Support Tools. 

Kernighan, B. W., and Ritchie, D. M., The C Programming Language, Second Edi- 
tion, Prentice-Hall, 1988. 

American National Standard for Information Systems - Programming Language 



Obsolescent but still recognized cc options include -f , -F, -YL, and -YU. The -ql 
and -0 options do not work together; -O will be ignored. 



C, X3.159-1989. 



NOTES 
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NAME 

cdc - change the delta comment of an SCCS delta 
SYNOPSIS 

cdc -r SID [^[mrlist] ] [ -y [comment] ] file... 
DESCRIPTION 

cdc changes the delta comment, for the SID (SCCS identification string) specified 
by the -r keyletter, of each named SCCS file. 

The delta comment is the Modification Request (MR) and comment information 
normally specified via the -m and -y keyletters of the delt:a command. 

If file is a directory, cdc behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and imreadable files are silently ignored. If a 
name of - is given, the standard input is read (see the NOTES section) and each 
line of the standard input is taken to be the name of an SCCS file to be processed. 

Arguments to cdc, which may appear in any order, consist of keyletter argu- 
ments and file names. 

All the described keyletter argimients apply independently to each named file: 

-rS/D Used to specify the SCCS JDentification (SID) string of a delta for 

which the delta comment is to be changed. 

--amrlist If the SCCS file has the v flag set [see admin(l)] then a list of MR 
numbers to be added and /or deleted in the delta comment of the 
SID specified by the -r keyletter may be supplied. A null MR list 
has no effect. 

mrlist entries are added to the list of MRs in the same manner as 
that of delta. In order to delete an MR, precede the MR number 
with the character ! (see the EXAMPLES section). If the MR to be 
deleted is currently in the list of MRs, it is removed and changed 
into a comment line. A list of all deleted MRs is placed in the 
comment section of the delta comment and preceded by a com- 
ment line stating that they were deleted. 

If -m is not used and the standard input is a terminal, the 
prompt MEis? is issued on the standard output before the stan- 
dard input is read; if the standard input is not a terminal, no 
prompt is issued. The j«s? prompt always precedes the ccm- 
xnents? prompt (see -y keyletter). 

mrlist entries in a list are separated by blanks and/or tab charac- 
ters. An unescaped new-line character terminates the MR list. 

Note that if the v flag has a value [see admind)], it is taken to be 
the name of a program (or shell procedure) that validates the 
correctness of the MR numbers. If a non-zero exit status is 
returned from the MR number validation program, cdc ter- 
minates and the delta comment remains unchanged. 
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-y[comment] 

Arbitrary text used to replace the comment (s) already existing for 
the delta specified by the -r keyletter. The previous comments 
are kept and preceded by a comment line stating that they were 
changed. A null comment has no effect. 

If -y is not specified and the standard input is a terminal, the 
prompt cx>mments? is issued on the standard output before the 
standard input is read; if the standard input is not a terminal, no 
prompt is issued. An unescaped new-line character terminates 
the comment text. 

If you made the delta and have the appropriate file permissions, you can change 
its delta comment. If you own the file and directory you can modify the delta 
comment. 

EXAMPLES 

cxic -rl.6 -m"bl88-12345 !bl87-54321 bl89-00001" -ytrouble s.file 

adds bl88-12345 and bl89-00001 to the MR list, removes bl87-54321 from the MR 
list, and adds the comment troiable to delta 1 .6 of s.file. 

Entering: 

cdc -rl.6 s.file 

MRS? !bl87-54321 bl88-12345 bl89-00001 
comnents? trouble 

produces the same result. 

FILES 

x-file [see deltad)] 
z-file [see delta(l)] 

SEE ALSO 

admind), deltad), get(l), help(l), prs(l), sccsf ile(4). 

DIAGNOSTICS 

Use help for explanations. 

NOTES 

If sees file names are supplied to the cdc command via the standard input (- on 
the command line), then the -m and -y keyletters must also be used. 
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NAME 

cf low - generate C flowgraph 
SYNOPSIS 

cflow [-r] [-ix] [-dnum] files 

DESCRIPTION 

The cflow command analyzes a collection of C, yacc, lex, assembler, and object 
files and builds a graph charting the external function references. Files suffixed 
with .y, .1, and .c are processed by yacc, lex, and the C compiler as appropri- 
ate. The results of the preprocessed files, and files suffixed with . i, are then run 
through the first pass of lint. Files suffixed with . s are assembled. Assembled 
files, and files suffixed with .o, have information extracted from their symbol 
tables. The results are collected and turned into a graph of external references 
that is written on the standard output. 

Each line of output begins with a reference number, followed by a suitable 
number of tabs indicating the level, then the name of the global symbol followed 
by a colon and its definition. Normally only function names that do not begin 
with an imderscore are listed (see the -i options below). For information 
extracted from C source, the definition consists of an abstract type declaration 
(e.g., char *), and, delimited by angle brackets, the name of the source file and 
the line number where the definition was found. Definitions extracted from 
object files indicate the file name and location counter under which the symbol 
appeared (e.g., text). Leading underscores in C-style external names are deleted. 
Once a definition of a name has been printed, subsequent references to that name 
contain only the reference nimiber of the line where the definition may be found. 
For undefined references, only <> is printed. 

As an example, suppose the following code is in file . c: 

int i; 

xnainO 
{ 

f(); 
gO; 
f 0; 

} 

f() 
{ 

i = h(); 

} 

The command 

cflow -ix file.c 
produces the output 



1 main : int ( ) , <f ile . c 4> 

2 f : into, <file.c 11> 

3 h: <> 

4 i: int, <file.c 1> 

5 g: <> 
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When the nesting level becomes too deep, the output of cf low can be piped to 
the pr command, using the -e option, to compress the tab expansion to some- 
thing less than every eight spaces. 

In addition to the -D, -I, and -U options [which are interpreted just as they are 
by cc], the following options are interpreted by cf low: 

-r Reverse the "callerxallee" relationship producing an inverted listing 
showing the callers of each function. The listing is also sorted in lexico- 
graphical order by callee. 

-ix Include external and static data symbols. The default is to include only 
functions in the flowgraph. 

Include names that begin with an underscore. The default is to exclude 
these fimctions (and data if -ix is used). 

-dnum The num decimal integer indicates the depth at which the flowgraph is 
cut off. By default this number is very large. Attempts to set the cutoff 
depth to a nonpositive integer will be ignored. 

SEE ALSO 

as(l), cc{l), lex(l), lint(l), nm(l), yacc(l). 
pr(l) in the Use/s Reference Manual. 

DIAGNOSTICS 

Complains about multiple definitions and only believes the first. 

NOTES 

Files produced by lex and yacc cause the reordering of line nimiber declarations, 
which can confuse cf low. To get proper results, feed cf low the yacc or lex 
input. 
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NAME 

chrtbl - generate character classification and conversion tables 

SYNOPSIS 

chrtJDl [file] 

DESCRIPTION 

The chrtbl command creates two tables containing information on character 
classification, upper/lower-case conversion, character-set width, and numeric 
editing. One table is an array of (257*2) + 7 bytes that is encoded so a table 
lookup can be used to determine the character classification of a character, con- 
vert a character (see ctypeOO), and find the byte and screen width of a charac- 
ter in one of the supplementary code sets. The other table is 2 bytes long: the 
first byte specifies the decimal delimiter; the second byte specifies the thousands 
delimiter. 

chrtbl reads the user-defined character classification and conversion information 
from file and creates three output files in the current directory. To construct file, 
use the file supplied in /usr/lib/locale/C/chrtbl__C as a starting point. You 
may add entries, but do not change the original values supplied with the system. 
For example, for other locales you may wish to add eight-bit entries to the ASQI 
definitions provided in this file. 

One output file, ctype.c (a C-language source file), contains a (257*2)+7-byte 
array generated from processing the information from file. You should review 
the content of ctype.c to verify that the array is set up as you had planned. (In 
addition, an application program could use ctype . c.) The first 257 bytes of the 
array in ctype . c are used for character classification. The characters used for ini- 
tializing these bytes of the array represent character classification? that are 
defined in /usr/include/ctype . h; for example, _L means a character is lower 
case and _S I JB means the character is both a spacing character and a blank. The 
second 257 bytes of the array are used for character conversion. These bytes of 
the array are initialized so that characters for which you do not provide conver- 
sion information will be converted to themselves. When you do provide conver- 
sion information, the first value of the pair is stored where the second one would 
be stored normally, and vice versa; for example, if you provide <0x41 0x6 1>, 
then 0x61 is stored where 0x41 would be stored normally, and 0x61 is stored 
where 0x41 would be stored normally. The last 7 bytes are used for character 
width information for up to three supplementary code sets. 

The second output file (a data file) contains the same information, but is struc- 
tured for efficient use by the character classification and conversion routines (see 
CtypeOO). The name of this output file is the value you assign to the keyword 
LC_CTYPE read in from file. Before this file can be used by the character 
classification and conversion routines, it must be installed in the 
/usr/lib/locale//ocwk directory with the name LC_CTYPE by someone who is 
super-user or a member of group bin. This file must be readable by user, group, 
and other; no other permissions should be set. To use the character classification 
and conversion tables in this file, set the LCjCTYPE environment variable 
appropriately (see environ(5) or setlocale(3C)). 
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The third output file (a data file) is created only if numeric editing information is 
specified in the input file. The name of this output file is the value you assign to 
the keyword LC__NUMERIC read in from file. Before this file can be used, it must 
be installed in the /usr/lih/ locale/ locale directory with the name LC_NUMERIC 
by someone who is super-user or a member of group bin. This file must be 
readable by user, group, and other; no other permissions should be set. To use 
the numeric editing information in this file, set the LC_NUMERIC environment vari- 
able appropriately (see environ(5) or setlocaleOO). 

The name of the locale where you install the files LCjCTYPE and LC_NUMERIC 
should correspond to the conventions defined in file. For example, if French con- 
ventions were defined, and the name for the French locale on your system is 
f rench, then you should install the files in /usr/ lib/ locale/ french. 

If no input file is given, or if the argument is encountered, chrtJ^l reads from 
standard input. 

The syntax of file allows the user to define the names of the data files created by 
chrtbl, the assignment of characters to character classifications, the relationship 
between upper and lower-case letters, byte and screen widths for up to three sup- 
piementaiy code sets, and two items of numeric editing information: the decimal 
delimiter and the thousands delimiter. The keywords recognized by chrtJDl are: 

name of the data file created by chrt±>l to contain 
character classification, conversion, and width informa- 
tion 

character codes to be classified as upper-case letters 

character codes to be classified as lower-case letters 

character codes to be classified as numeric 

character codes to be classified as spacing (delimiter) 
characters 

character codes to be classified as punctuation charac- 
ters 

character codes to be classified as control characters 

character code for the blank (space) character 

character codes to be classified as hexadecimal digits 

relationship between upper- and lower-case characters 

byte and screen width information (by default, each is 
one character wide) 

name of the data file created by chrtbl to contain 
numeric editing information 

decimal delimiter 

thousands delimiter 



LCJCTYPE 

isupper 
islower 
isdigit 
isspace 

ispunct 

iscntrl 
isblank 
isxdigit 
ul 

cswidth 

LCJTOMERIC 

decimaljpoint 
thousandsjsep 
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Any lines with the number sign (#) in the first column are treated as comments 
and are ignored. Blank lines are also ignored. 

Characters for isupper, is lower, isdigit, isspace, ispunct, iscntrl, 
isblank, isxdigit, and ul can be represented as a hexadecimal or octal constant 
(for example, the letter a can be represented as 0x61 in hexadecimal or 0141 in 
octal). Hexadecimal and octal constants may be separated by one or more space 
and /or tab characters. 

The dash character (~) may be used to indicate a range of consecutive numbers. 
Zero or more space characters may be used for separating the dash character 
from the numbers. 

The backslash character (\) is used for line continuation. Only a carriage return 
is permitted after the backslash character. 

The relationship between upper- and lower-case letters (ul) is expressed as 
ordered pairs of octal or hexadecimal constants: <upper-case_character lower- 
case _character>. These two constants may be separated by one or more space 
characters. Zero or more space characters may be used for separating the angle 
brackets (< >) from the numbers. 

The following is the format of an input specification for cswidtJi: 

nl:sl,n2:s2,n3:s3 

where, 

nl byte width for supplementary code set 1, required 

si screen width for supplementary code set 1 

nl byte width for supplementary code set 2 

s2 screen width for supplementary code set 2 

n3 byte width for supplementary code set 3 

s3 screen width for supplementary code set 3 

EXAMPLE 

The following is an example of an input file used to create the ASQI code set 
definition table in a file named ascii. 



LC^CTYPE 


ascii 






isupper 


0x41 


- 0x5a 






islower 


0x61 


- 0x7a 






isdigit 


0x30 


- 0x39 






isspaoe 


0x20 


0x9 - Oxd 




ispuict 


0x21 


" 0x2f 


0x3a - 


0x40 \ 




0x5b 


- 0x60 


OxTb - 


0x7e 


iscntrl 


0x0 - 


- Oxlf 


0x7f 




isblank 


0x20 








isxdigit 


0x30 


- 0x39 


0x61 - 


0x66 \ 




0x41 


- 0x46 






ul 


<0x41 


0x61> <0x42 0x62> <0x43 



<0x44 0x64> <0x45 0x65> <0x46 0x66> \ 

<0x47 0x67> <0x48 0x68> <0x49 Qx69> \ 

<0x4a 0x6a> <0x4b 0x6b> <0x4c 0x60 \ 

<0x4d 0x6d> <0x4e 0x6e> <0x4f 0x6f> \ 

<0x50 0x70> <0x51 0x71> <0x52 0x72> \ 

<0x53 0x73> <0x54 0x74> <0x55 0x75> \ 
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<0x56 0x76> <0x57 0x77> <0x58 0x78> \ 

<0x59 0x79> <0x5a 0x7a> 
cswidth 1:1,0:0^0:0 
ICJfJMEBlC numascii 
decimaljpoint 
thousandsjsep , 

FILES 

/usr/lib/locale//oa2k/LC_CTYPE 

data files containing character classification, conversion, and 

character-set width information created by chrtbl 
/usr/lib/locale/tocak/LC_NUMERIC 

data files containing numeric editing information created by 

chrtbl 

/usr/include/ctype .h 

header file containing information used by character 

classification and conversion routines 
/usr/lib/locale/C/chrtbl_C 

input file used to construct LC_CTYPE and LC_NUMERIC in the 

default locale. 

SEE ALSO 

environ(5). 

ctypeOO, setlocaleOO in the Programmer's Reference Manual. 
DIAGNOSTICS 

The error messages produced by chrtbl are intended to be self-explanatory. 
They indicate errors in the command line or syntactic errors encountered within 
the input file. 

WARNING 

Changing the files in /usr/lib/locale/C will cause the system to behave 
unpredictably. 
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NAME 

cof 2elf - COFF to ELF object file translation 
SYNOPSIS 

cof2elf [-iqV] [-Q{yn}] [-3 directory] files 
DESCRIPTION 

cof 2elf converts one or more COFF object files to ELF. This translation occurs 
in place, meaning the original file contents are modified. If an input file is an 
archive, each member will be translated as necessary, and the archive will be 
rebuilt with its members in the original order. cof2elf does not change input 
files that are not COFF. 

Options have the following meanings. 

-i Normally, the files are modified only when full translation occurs. 

Unrecognized data, such as unknown relocation types, are treated as 
errors and prevent translation. Giving the -i flag ignores these par- 
tial translation conditions and modifies the file anyway. 

-q Normally, cof 2elf prints a message for each file it examines, telling 

whether the file was translated, ignored, etc. The -q flag (for quiet) 
suppresses these messages. 

-Qarg If arg is y, identification information about cof 2elf will be added to 

the output files. This can be useful for software administration. 
Giving n for arg explicitly asks for no such information, which is the 
default behavior. 

-sdirectory As mentioned above, cof 2 elf modifies the input files. This option 
saves a copy of the original files in the specified directory, which 
must exist. cof2elf does not save files it does not modify. 

-V This flag tells cof 2elf to print a version message on standard error. 

SEE ALSO 

Idd), elf(3E), a.out(4), ar(4). 

NOTES 

Some debugging information is discarded. Although this does not affect the 
behavior of a running program, it may affect the information available for sym- 
bolic debugging. 

cof 2elf translates only COFF relocatable files. It does not translate executable or 
static shared library files for two main reasons. First, the operating system sup- 
ports executable files and static shared libraries, making translation unnecessary. 
Second, those files have specific address and alignment constraints determined by 
the file format. Matching the constraints with a different object file format is 
problematic. 

When possible, programmers should recompile their source code to build new 
object files, cof 2elf is provided for those times when source code is imavailable. 
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NAME 

colltbl - create collation database 

SYNOPSIS 

colltbl [ file I " ] 

DESCRIPTION 

The colltbl command takes as input a specification file, file, that describes the 
collating sequence for a particular language and creates a database that can be 
read by strxfrmOC) and strcoll(3C). strxfrmOC) transforms its first argu- 
ment and places the result in its second argument. The transformed string is such 
that it can be correctly ordered with other transformed strings by using 
strcnp(3C), strncmpOC) or meiranpOC). strcollOC) transforms its arguments 
and does a comparison. 

If no input file is supplied, stdin is read. 

The output file produced contains the database with collating sequence informa- 
tion in a form usable by system commands and routines. The name of this out- 
put file is the value you assign to the keyword codeset read in from file. Before 
this file can be used, it must be installed in the /usr/lib/locale//ocflk directory 
with the name LCJCOIXATE by someone who is super-user or a member of group 
bin. locale corresponds to the language area whose collation sequence is 
described in file. Tliis file must be readable by user, group, and other; no other 
permissions should be set. To use the collating sequence information in this file, 
set the LCJCOLLATE environment variable appropriately (see environ(5) or 
setlocaleOO). 

The colltbl command can support languages whose collating sequence can be 
completely described by the following cases: 

• Ordering of single characters within the codeset. For example, in Swedish, V 
is sorted after U, before X and with W (V and W are considered identical as far 
as sorting is concerned). 

• Ordering of "double characters" in the collation sequence. For example, in 
Spanish, ch and 11 are collated after c and 1, respectively. 

• Ordering of a single character as if it consists of two characters. For exam- 
ple, in German, the "sharp s", P, is sorted as ss. This is a special instance of 
the next case below. 

• Substitution of one character string with another character string. In the 
example above, the string P is replaced with ss during sorting. 

• Ignoring certain characters in the codeset during collation. For example, if - 
were ignored during collation, then the strings re-locate and relocate 
would be equal. 

• Secondary ordering between characters. In the case where two characters are 
sorted together in the collation sequence, (i.e., they have the same "primary" 
ordering), there is sometimes a secondary ordering that is used if two strings 
are identical except for characters that have the same primary ordering. For 
example, in French, the letters e and h have the same primary ordering but e 
comes before e in the secondary ordering. Thus the word lever would be 
ordered before lever, but lever would be sorted before levitate. (Note 
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that if e came before e in the primary ordering, then lever would be sorted 
after levitate.) 

The specification file consists of three types of statements: 

1. codeset filename 

filename is the name of the output file to be created by colltbl. 

2. order is order Jist 

order Jist is a list of symbols, separated by semicolons, that defines the collat- 
ing sequence. The special symbol, . . ., specifies symbols that are lexically 
sequential in a short-hand form. For example, 
order is a; b; c; d; . . . ; x; y ; z 

would specify the list of lower_case letters. Of course, this could be further 
compressed to just a; . . . ; z. 

A symbol can be up to two bytes in length and can be represented in any 
one of the following ways: 

• the symbol itself (e.g., a for the lower-case letter a), 

• in octal representation (e.g., \141 or 0141 for the letter a), or 

• in hexadecimal representation (e.g., \x61 or 0x61 for the letter a). 
Any combination of these may be used as well. 

The backslash character, \ , is used for continuation. No characters are per- 
mitted after the backslash character. 

Symbols enclosed in parenthesis are assigned the same primary ordering but 
different secondary ordering. Symbols enclosed in curly brackets are 
assigned only the same primary ordering. For example, 

order is a; b; c; ch; d; (e; e) ; f ; . . . ; z ; \ 
{1;...;9};A;...;Z 

In the above example, e and e are assigned the same primary ordering and 
different secondary ordering, digits 1 through 9 are assigned the same pri- 
mary ordering and no secondary ordering. Only primary ordering is 
assigned to the remaining symbols. Notice how double letters can be 
specified in the collating sequence (letter ch comes between c and d). 

If a character is not included in the order is statement it is excluded from 
the ordering and will be ignored during sorting. 

3. substitute string with rej)l 

The substitute statement substitutes the string siring with the string repl. 
This can be used, for example, to provide rules to sort the abbreviated month 
names numerically: 
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substitute "Jan" with "01" 
substitute "Feb" with "02" 



substitute "Dec" with "12" 

A simpler use of the substitute statement that was mentioned above was 
to substitute a single character with two characters, as with the substitution 
of P with ss in German. 

The substitute statement is optional. The order is and codeset statements 
must appear in the specification file. 

Any lines in the specification file with a # in the first column are treated as com- 
ments and are ignored. Empty lines are also ignored. 

EXAMPLE 

The following example shows the collation specification required to support a 
hypothetical telephone book sorting sequence. 

The sorting sequence is defined by the following rules: 

a. Upper and lower case letters must be sorted together, but upper case 
letters have precedence over lower case letters. 

b. All special characters and punctuation should be ignored. 

c. Digits must be sorted as their alphabetic counterparts (e.g., 0 as zero, 1 as 
one). 

d. The Ch, ch, CH combinations must be collated between C and D. 

e. V and W, v and w must be collated together. 
The input specification file to colltbl will contain: 

codeset telephone 

order is A;a;B;b;C;c;CH;Ch;ch;D/d;E;e;F;f ;\ 

G; g; H; h : I ; i ; J; j ; K; k ; L; 1 ; M; m; N ; n ; 0 ; o ; P ; p ; \ 
Q;q;R;r;S;s;T;t;U;u;{V;W};{v;w};X;x;Y;y;Z;z 



siabstitute 


»'0" 


with 


"zero" 


substitute 




with 


"one" 


substitute 


"2" 


with 


"two" 


substitute 


113 II 


wit:h 


"three" 


substitute 


"4" 


with 


"four" 


substitute 


11511 


witJi 


"five" 


substitute 


"6" 


wit:h 


"six" 


substitute 


If 


wit:h 


"seven" 


substitute 


"8" 


with 


"eight" 


substitute 


"9" 


with 


"nine" 
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FILES 

/lib/locale/tocwk/LC_OOLLATE 

LCjOOLLATE database for locale 

/usr/lib/lcx:ale/C/colltbljC 

input file used to construct LC_COLLATE in the default locale. 

SEE ALSO 

mextory(3C), setlocale(3C), strcollOC), string(3C), strxfrmOO, environ(5) 
in the Programmer's Reference Manual. 
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SYNOPSIS 
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DESCRIPTION 

comb generates a shell procedure [see sh(l)] that, when run, reconstructs the 
given SCCS files. The reconstructed files are typically smaller than the original 
files. The argtiments may be specified in any order, but aU keyletter arguments 
apply to all named SCCS files. If a directory is named, cento behaves as though 
each file in the directory were specified as a named file, except that non-SCCS files 
(last component of the path name does not begin with s . ) and unreadable files 
are silently ignored. If a name of - is given, the standard input is read; each line 
of the input is taken to be the name of an SCCS file to be processed; non-SCCS 
files and unreadable files are silently ignored. The generated shell procedure is 
written on the standard output. 

The keyletter arguments are as follows. Each argument is explained as if only 
one named file is to be processed, but the effects of any keyletter argument apply 
independently to each named file. 

-o For each get -e, this argument causes the reconstructed file to be 
accessed at the release of the delta to be created, otherwise the recon- 
structed file would be accessed at the most recent ancestor. Use of the -o 
keyletter may decrease the size of the reconstructed SCCS file. It may also 
alter the shape of the delta tree of the original file. 

-s This argument causes conto to generate a shell procedure that, when run, 
produces a report that gives for each file: the file name, size (in blocks) 
after combining, original size (also in blocks), and percentage change com- 
puted by: 

100 * (original - combined) / original 

It is recommended that before any SCCS files are actually combined, one 
should use this option to determine exactly how much space is saved by 
the combining process. 

-pSJD The SCCS identification string (SID) of the oldest delta to be preserved. All 
older deltas are discarded in the reconstructed file. 

-clist A list of deltas to be preserved. All other deltas are discarded. See get(l) 
for the syntax of a list 

If no keyletter arguments are specified, conto preserves only leaf deltas and the 
minimal number of ancestors needed to preserve the tree. 

FILES 

s . COMB the reconstructed SCCS file 

conto????? temporary file 

SEE ALSO 

admind), delta(l), get(l), help(l), prs(l), sccsf ile(4). 
sh(l) in the User's Reference Manual 
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DIAGNOSTICS 

Use help(l) for explanations. 

NOTES 

coxnb may rearrange the shape of the tree of deltas. 

comb may not save any space; in fact, it is possible for the reconstructed file to be 
larger than the original. 
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NAME 

convert - convert archive files to common formats 

SYNOPSIS 

convert [-x] infile outfile 

DESCRIPTION 

The convert command transforms input infilel to output outfile. infile must be a 
UNIX System V Release 1.0 archive file and outfile will be the equivalent UNIX 
System V Release 2.0 archive file. All other types of input to the convert com- 
mand will be passed unmodified from the input file to the output file (along with 
appropriate warning messages). 

The -X option is required to convert a XENIX archive. (XENIX is a registered 
trademark of Microsoft Corporation.) Using this option will convert the general 
archive but leave archive members unmodified. 

infile must be different from outfile. 

FILES 

TMPDIR/conv* temporary files 

TMPDIR is usually /usr/tirp but can be redefined by setting the environment 
variable IMPDIR [see tenpnamO in tirpnamOS)]. 

SEE ALSO 

ar(l), titpnamOS), a. out (4), ar(4). 
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NAME 

cscope - interactively examine a C program 

SYNOPSIS 

cscope [options] files, . . 

DESCRIPTION 

cscope is an interactive screen-oriented tool that allows the user to browse 
through C source files for specified elements of code. 

By default, cscope examines the C (.c and .h), lex (.1), and yacc (.y) source 
files in the current directory, cscope may also be invoked for source files named 
on the command line. In either case, cscope searches the standard directories for 
♦include files that it does not find in the current directory, cscope uses a sym- 
bol cross-reference, escape. out by default, to locate fimctions, function calls, 
macros, variables, and preprocessor symbols in the files. 

cscope builds the symbol cross-reference the first time it is used on the source 
files for the program being browsed. On a subsequent invocation, cscope 
rebuilds the cross-reference only if a source file has changed or the list of source 
files is different. When the cross-reference is rebuilt, the data for the unchanged 
files are copied from the old cross-reference, which makes rebuilding faster than 
the initial build. 

The following options can appear in any combination: 
-b Build the cross-reference only. 

-C Ignore letter case when searching. 

-c Use only ASCII characters in the cross-reference file, that is, do 

not compress the data. 

-d Do not update the cross-reference. 

-e Suppress the ^e command prompt between files. 

-f refple Use reffile as the cross-reference file name instead of the default 

cscope. out. 

-I incdir Look in incdir (before looking in INCDIR, the standard place for 

header files, normally /usr/ include) for any #include files 
whose names do not begin with / and that are not specified on 
the command line or in namefile below. (The #include files may 
be specified with either double quotes or angle brackets.) The 
incdir directory is searched in addition to the current directory 
(which is searched first) and the standard list (which is searched 
last). If more than one occurrence of -I appears, the directories 
are searched in the order they appear on the command line. 

-i namefile Browse through all source files whose names are listed in namefile 
(file names separated by spaces, tabs, or new-lines) instead of the 
default (cscope . files). If this option is specified, cscope 
ignores any files appearing on the command line. 
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-L Do a single search with line-oriented output when used with the 

-num. pattern option. 

-1 Line-oriented interface (see "Line-Oriented Interface" below). 

-num pattern Go to input field num (counting from 0) and find pattern. 

-P path Prepend path to relative file names in a pre-built cross-reference 

file so you do not have to change to the directory where the 
cross-reference file was built. This option is only valid with the 
-d option. 

~p n Display the last n file path components instead of the default (1). 

Use 0 to not display the file name at all. 

-s dir Look in dir for additional source files. This option is ignored if 

source files are given on the command line. 

-T Use only the first eight characters to match against C symbols. A 

regular expression containing special characters other than a 
period (.) will not match any symbol if its minimum length is 
greater than eight characters. 

-U Do not check file time stamps (assume that no files have 

changed). 

-u Unconditionally build the cross-reference file (asstime that all 

files have changed). 

-V Print on the first line of screen the version number of cscope. 

The -I, -p, and -T options can also be in the cscope . files file. 

Requesting the Initial Search 

After the cross-reference is ready, cscope will display this menu: 

Find this C syirbol: 

Find this function definition : 

Find functions called by this function: 

Find functions calling this function: 

Find this text string: 

Change this text string: 

Find this egrep pattern: 

Find this file: 

Find files #including this file: 

Press the TAB key repeatedly to move to the desired input field, type the text to 
search for, and then press the RETURN key. 

Issuing Subsequent Requests 

If the search is successful, any of these single-character commands can be used: 



1-9 Edit the file referenced by the given line number. 

SPACE Display next set of matching lines. 
+ Display next set of matching lines. 



Page 2 10/89 



cscope(1) cscope(1) 

- Display previous set of matching lines, 

'^e Edit displayed files in order. 

> Append the displayed list of lines to a file. 

I Pipe all lines to a shell command. 

At any time these single-character commands can also be used: 

TAB Move to next input field. 

RETURN Move to next input field, 

'"'n Move to next input field. 

Move to previous input field, 

'^y Search with the last text typed, 

'^b Move to previous input field and search pattern, 

"^f Move to next input field and search pattern. 

''c Toggle ignore/use letter case when searching. (When ignoring letter 

case, search for FILE will match File and file.) 

'^r Rebuild the cross-reference. 

! Start an interactive shell (type ''d to return to cscx>pe). 

'^l Redraw the screen. 

? Give help information about cscope commands, 

'^d Exit cscope. 



Note: If the first character of the text to be searched for matches one of the above 
commands, escape it by typing a \ (backslash) first. 

Substituting New Text for Old Text 

After the text to be changed has been typed, cscope will prompt for the new 
text, and then it will display the lines containing the old text. Select the lines to 
be changed with these single-character commands: 



1-9 Mark or unmark the line to be changed. 

* Mark or unmark all displayed lines to be changed. 

SPACE Display next set of lines. 

+ Display next set of lines. 

- Display previous set of lines. 

a Mark all lines to be changed. 

''d Change the marked lines and exit. 

ESCAPE Exit without changing the marked lines. 

! Start an interactive shell (type ''d to return to cscope). 

'^l Redraw the screen. 

? Give help information about cscope commands. 



Special Keys 

If your terminal has arrow keys that work in vi(l), you can use them to move 
around the input fields. The up-arrow key is useful to move to the previous 
input field instead of using the TAB key repeatedly. If you have CLEAR^ NEXT, or 
PREV keys they will act as the '^1, +, and - commands, respectively. 

Line-Oriented Interface 

The -1 option lets you use cscope where a screen-oriented interface would not 
be useful, e.g., from another screen-oriented program. 

cscope will prompt with » when it is ready for an input line starting with the 
field number (counting from 0) immediately followed by the search pattern, e.g.. 
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Imain finds the definition of the main function. If you just want a single search, 
instead of the -1 optioh use the ^ and -num pattern options, and you won't get 
the >> prompt. 

For ^1, cscope outputs the number of reference lines 
cscope: 2 lines 

For each reference found, cscope outputs a line consisting of the file name, func- 
tion name, line number, and line text, separated by spaces^ e.g,, 

main. c main 161 mainCargc^ argv) 
Note that the editor is not called to display a single reference, unlike the screen- 
oriented interface. 

You can use the r command to rebuild the database. 

cscope will quit when it detects end-of-file, or when the first character of an 
input line is ''d or q. 

ENVIRONMENT VARIABLES 



EDITOR 

INCLUDEDIRS 

HOME 

SHELL 

SOURCEDIRS 

TERM 
TERMINFO 



TMPDIR 
VIEWER 



VPATH 



Preferred editor, which defaults to vi(l). 
Colon-separated list of directories to search for #include files. 
Home directory, which is automatically set at login. 
Preferred shell, which defaults to sh(l). 

Colon-separ^t^ lis* of directories to search for additional source 
files. 

Terminal type, which must be a screen terminal. 
Terminal information directory full path name. If your terminal 
is not in the standard terminf o directory, see curses and ter- 
minf o for how to make your own terminal description. 
Temporary file directory, which defaults to /usr/tnp. 
Preferred file display program {such as pg], which overrides EDI- 
TOR (see above). 

A colon-separated list ®f directories^ i^h 6f which has the same 
directory structure below it. If VPATH is set, cscope searches for 
source files in the directories specified; if it is not set, cscope 
searches only in the current directory. 



FILES 



^scdpe. files Default files containing -I, -p, and -T options and the list of 
source files (overridden by the -i option). 

cscope . out Symbol cross-reference file, which is put in the home directory if 
it cannot be created in the current directory. 

ncscop^^.out Temporary file containing hew cross-refetence before it replaces 
the old cross*reference. 

INCDIR Standard dir^ctbry for tincliide files (usually /usr/ include). 

SEE ALSO 

The ' -cscope" chapter in the Programmer's Guide: ANSI C and Programming Sup- 
port Tools. 

curses and terminfo in the Programmer's Guide: Character User Interface (FMLI 
and EtI), 
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NOTES 

cscope recognizes function definitions of the form: 
fmme blank ( args ) white arg_dec$ white { 



where: 




fmme 


is the function name 


blank 


is zero or more spaces or tabs, not including newlines 


args 


is any string that does not contain a " or a newline 


white 


is zero or more spaces, tabs, or newlines 


argjiecs 


are zero or more argument declarations (argjiecs may include com- 


ments and white space) 



It is not necessary for a function declaration to start at the beginning of a line. 
The return type may precede the function name; cscope will still recognize the 
declaration. Function definitions that deviate from this form will not be recog- 
nized by escape. 



The Function column of the search output for the menu option Find functions 
called by this fimction: input field will only display the first function 
called in the line, that is, for this function 

e() 
{ 

return (f () + gO); 

} 

the display would be 

Functions called by this function: e 

File Function Line 

a.c f 3 return (f() +g()); 

Occasionally, a function definition or call may not be recognized because of 
braces inside #if statements. Similarly, the use of a variable may be incorrectly 
recognized as a definition. 

A typedef name preceding a preprocessor statement will be incorrectly recog- 
nized as a global definition, e.g., 

LDFILE * 

#if AR16WR 

Preprocessor statements can also prevent the recognition of a global definition, 
char flag 

fifdef MiLOCATE^STORAGE 

= -1 
#endif 
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A function declaration inside a function is incorrectly recognized as a function 
calle.g., 

f() 
{ 

void g() ; 

) 

is incorrectly recognized as a call to g ( ) . 

cscope recognizes C++ classes by looking for the class keyword, but doesn't 
recognize that a struct is also a class, so it doesn't recognize inline member 
function definitions in a structure. It also doesn't expect the class keyword in a 
typedef, so it incorrectly recognizes X as a definition in 

typedef class X * Y; 
It also doesn't recognize operator function definitions 

Bool Feature : : operator— (const Feature & ot:her ) 

{ 

} 
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NAME 

ctrace - C program debugger 

SYNOPSIS 

ctrace [options] [file] 

DESCRIPTION 

The ctrace command allows the user to monitor the sequential execution of a C 
program as each program statement executes. The effect is similar to executing a 
shell procedure with the -x option, ctrace reads the C program in file (or from 
standard input if the user does not specify file), inserts statements to print the text 
of each executable statement and the values of all variables referenced or 
modified, and writes the modified program to the standard output. The output 
of ctrace must be placed into a temporary file because the cc(l) command does 
not allow the use of a pipe. This file can then be compiled and executed. 

As each statement in the program executes, it will be listed at the terminal, fol- 
lowed by the name and value of any variables referenced or modified in the 
statement; these variable names and values will be followed by any output from 
the statement. Loops in the trace output are detected and tracing is stopped until 
the loop is exited or a different sequence of statements within the loop is exe- 
cuted. A warning message is printed after each 1000 loop cycles to help the user 
detect infinite loops. The trace output goes to the standard output so the user 
can put it into a file for examination with an editor or the bf s(l) or tail(l) com- 
mands. 

The options commonly used are: 

-f functions Trace only these functions. 
-V functions Trace all but these functions. 

The user may want to add to the default formats for printing variables. Long 
and pointer variables are always printed as signed integers. Pointers to character 
arrays are also printed as strings if appropriate, char, short, and int variables 
are also printed as signed integers and, if appropriate, as characters, double 
variables are printed as floating point numbers in scientific notation. The user 
can request that variables be printed in additional formats, if appropriate, with 
these options: 

~o Octal 
-X Hexadecimal 
-u Unsigned 
-e Floating point 

These options are used only in special circumstances: 

-1 n Check n consecutively executed statements for looping trace output, 

instead of the default of 20. Use 0 to get all the trace output from loops, 
-s Suppress redundant trace output from simple assignment statements and 

string copy function calls. This option can hide a bug caused by use of 

the = operator in place of the == operator, 
-t n Trace n variables per statement instead of the default of 10 (the maximum 

number is 20). The diagnostics section explains when to use this option. 
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-P Preprocess the input before tracing it. The user can also use the -D, -I, 

and -U cc(l) options, 
-p string 

Change the trace print function from the defauU of printf . For example, 
fprintf (stderr, would send the trace to the standard error output. 

-r / Use file / in place of the runtime. c trace function package. This replace- 
ment lets the user change the entire print function, instead of just the 
name and leading arguments (see the -p option). 

-V Prints version information on the standard error. 

-Qfirg If arg is y, identification information about ctrace will be added to the 
output files. This can be useful for software administration. Giving n for 
arg exlicitly asks for no such information, which is the default behavior. 

EXAMPLE 

If the file Ic.c contains this C program: 

1 tincXude <stdio.h> 

2 xoainO /* count lines in input */ 



3 { 




4 


int nl; 


5 




6 


nl = 0; 


7 


*^ile ( (c = getcharO ) 


8 


if (c = ' \n' ) 


9 


-H-nl; 


10 


printf ("%d\n", nl) ; 


11 } 





these commands and test data are entered: 

cc I cc 
a. out 
1 

(cntl-d) 

the program will be compiled and executed. The output of the program will be 
the number 2, which is incorrect because there is only one line in the test data. 
The error in this program is ^common, but subtle. If the user invokes ptrace 
with these commands: 

ctrace Ic.c >tenp.c 
cc t^inp.c 
a . out 

the outpii* will be: 

2 inainO 

6 nl « 0; 

/* nl = 0 */ 

7 %rtiile <(c = getcharO) != EOF) 



The pfbgi^ irotv wsati^^ fof mpM. If user ^iiiteirs? te^ d^a? a^^ 

befb^ tliie diitpilit will be: 

c # oi: 'i' "i^/ 

/^^ e M 6^ */ 

§ 44^f 

/r 6 iO or ' W 

/i^' M ^ 2? #/ 

M afei csiSd^f-file' cMra^ (ciitM) eiiteiredy ffle viiffl bi^ 

/*■ 6 ^ -i- 

hi — ^ 
retLurri 

Mote the i^fbf itiatibA printed out at the end of the ti'ace liiie for the ni variable 
folfewing. line 10. Aliso note the t^tistti eomm^nt added by ctjfac^i at the end of 
the trate output. This shows the implicit rettirn at th6 terMnatihg brace in the 
function. 

The trac^ output shows that variable c is assigned the value 'l' in line 7, but in 
line 8 it has the value '\n'. Once user attention is dtawn to this if statement, he 
or she will probably realize that the assignment operator W was used in place of 
the equality operator This eitor 6an easily be missal during code riding. 

EXECiiTION-TltoE TRACE CONTROL 

The default operation for ctrace is to trace the entire program file, unless the -f 
or -V options are used to trace specific functions. The default operation does not 
give the user statement-by-statement control of the tracing, nor does if let the 
user turn tlie tracing off and o^ whert executing the traced program. 

The iiser can do both of these by M^ing c€r6f f (> arid ctronO ftin6ti6ft Calls to 
the program to turn the tracing off arid on, respectively, at execution time. Thus, 
complex criteria can be arbitrarily coded for trace control with if statements, and 
this code can even be conditionally included beiEause' ctrace defines the CtE^EU^lS 
preprocessor variable. For tompte 

etsron: () / 

feridif 

These fimctions can also be called from sdb(l) if they are compiled with the -q 
option. For example, to trace all but lines 7 to 10 in the main function, enter: 
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sdb a . out 
main :7b ctroff () 
main: lib ctronO 
r 

The trace can be turned off and on by setting static variable tr__ct_ to 0 and 1, 
respectively. This on/off option is useful if a user is using a debugger that can 
not call these functions directly. 

FILES 

/usr/ccs/lib/ctrace/runtime . c run-time trace package 

SEE ALSO 

sdb(l), ctypeOC), fclose(3S), printf (3S), string(3C). 
bf s(l), tail(l) in the User's Reference Manual. 

DIAGNOSTICS 

This section contains diagnostic messages from both ctrace and cc(l), since the 
traced code often gets some cc warning messages. The user can get cc error 
messages in some rare cases, all of which can be avoided. 

ctrace Diagnostics 

warning: some variables are not traced in this statement 

Only 10 variables are traced in a statement to prevent the C compiler "out 
of tree space; simplify expression" error. Use the -t option to increase 
this number. 

warning: statement too long to trace 

This statement is over 400 characters long. Make sure that tabs are used 
to indent the code, not spaces. 

cannot handle preprocessor code, use -P option 

This is usually caused by #ifdef /#endif preprocessor statements in the 
middle of a C statement, or by a semicolon at the end of a #define 
preprocessor statement. 

'if ... else if sequence too long 

Split the sequence by removing an else from the middle. 

possible syntax error, try -P option 

Use the -P option to preprocess the ctrace input, along with any 
appropriate -D, -I, and -U preprocessor options. 

NOTES 

Defining a function with the same name as a system function may cause a syntax 
error if the number of arguments is changed. Just use a different name. 

ctrace assumes that BADMZ^G is a preprocessor macro, and that EOF and NULL are 
#defined constants. Declaring any of these to be variables, e.g., "int EOF;", will 
cause a syntax error. 

Pointer values are always treated as pointers to character strings. 
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ctrace does not know about the components of aggregates like structures, 
unions, and arrays. It cannot choose a format to print all the components of an 
aggregate when an assignment is made to the entire aggregate, ctrace may 
choose to print the address of an aggregate or use the wrong format (e.g., 
3.149050e-311 for a structure with two integer members) when printing the 
value of an aggregate. 

The loop trace output elimination is done separately for each file of a multi-file 
program. Separate output elimination can result in functions called from a loop 
still being traced, or the elimination of trace output from one function in a file 
until another in the same file is called. 
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NAME 

cxref - generate C program cross-reference 

SYNOPSIS 

cxref [options] files 

DESCRIPTION 

The cxref command analyzes a collection of C files and builds a cross-reference 
table, cxref uses a special version of cc to include #def ine'd information in its 
symbol table. It generates a list of all symbols (auto, static, and global) in each 
individual file, or, with the -c option, in combination. The table includes four 
fields: NAME, FILE, FUNCTION, and LINE. The line numbers appearing in the 
LINE field also show reference marks as appropriate. The reference marks 
include: 

assignment = 
declaration - 
definition * 



If no reference marks appear, you can assume a general reference. 
OPTIONS 

cxref interprets the -D, -I, -U options in the same manner that cc does. In 
addition, cxref interprets the following options: 

-c Combine the source files into a single report. Without the -c option, 
cxref generates a separate report for each file on the command line. 

-d Disables printing declarations, making the report easier to read. 

-1 Does not print local variables. Prints only global and file scope statistics. 

-o file Direct output to file, 

-a Operates silently; does not print input file names, 

-t Format listing for 80-column width. 

-wnum Width option that formats output no wider than num. (decimal) columns. 
This option will default to 80 if num is not specified or is less than 51. 

-C Runs only the first pass of cxref, creating a .cx file that can later be 
passed to cxref. This is similar to the -c option of cc or lint. 

~F Prints the full path of the referenced file names. 

-Lcofe Modifies the number of columns in the LINE field. If you do not specify 
a number, cxref defaults to five columns. 

-V Prints version information on the standard error. 

-^Rnamefile, function, line 

Changes the default width of at least one field. The default widths are: 

Field Characters 

NAME 15 

RLE 13 

FUNCTION 15 

LINE 20 (4 per column) 
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FILES 

TMPDIR/tCK.* 
TMPDIR/cx.* 
LIBDIR/xref 

LIBDIR 
TMPDIR 

EXAMPLE 

a.c 

1 mainO 

2 { 

3 int i; 

4 extern char c; 
5 

6 i=65; 

7 c=(char)i; 

8 } 



Resulting cross-reference table: 



NAME 


FILE 


FUNCTION 


LINE 


c 


a.c 




4- 


i 


a.c 


main 


3* 


main 


a.c 




2* 


u3b2 


predefined 




0* 


unix 


predefined 




0* 



SEE ALSO 

cc(l), lint(l). 

DIAGNOSTICS 

Error messages usually mean you cannot compile the files. 



temporary files 
temporary files 
accessed by cxref 

usually /usr/ccs/lib 

usually /usr/tnp but can be redefined by setting the 
environment variable TMPDIR [see tenpnam in tnpnaWsS)]. 
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NAME 

delta - make a delta (change) to an SCCS file 
SYNOPSIS 

delta l-rSID] [-s] [-n] l-glist] l-fcimrlist]] [-ylcomment]] [-p] files 
DESCRIPTION 

delta is used to permanently introduce into the named SCCS file changes that 
were made to the file retrieved by get -e (called the g-file or generated file). 

delta makes a delta to each named SCCS file. If a directory is named, delta 
behaves as though each file in the directory were specified as a named file, except 
that non-SCCS files (last component of the path name does not begin with s.) 
and unreadable files are silently ignored. If a name of - is given, the standard 
input is read (see the NOTES section); each line of the standard input is taken to 
be the name of an SCCS file to be processed. 

delta may issue prompts on the standard output depending on certain keyletters 
specified and flags [see admind)] that may be present in the SCCS file (see -m and 
-y keyletters below). 

Keyletter arguments apply independently to each named file. 

-rSJD Uniquely identifies which delta is to be made to the SCCS 

file. The use of this keyletter is necessary only if two or 
more outstanding gets for editing (get -e) on the same 
SCCS file were done by the same person (login name). The 
SID value specified with the -r keyletter can be either the 
SID specified on the get command line or the SID to be 
made as reported by the get command [see get(l)]. A 
diagnostic results if the specified SID is ambiguous, or, if 
necessary and omitted on the command line. 

Suppresses the issue, on the standard output, of the created 
delta's SID, as well as the number of lines inserted, deleted 
and unchanged in the SCCS file. 

Specifies retention of the edited g-file (normally removed at 
completion of delta processing). 

Specify a list [see get(l) for the definition of list] of deltas 
that are to be ignored when the file is accessed at the 
change level (SID) created by this delta. 

If the SCCS file has the v flag set [see admin(l)] then a 
Modification Request (MR) number must be supplied as the 
reason for creating the new delta. If -m is not used and the 
standard input is a terminal, the promjrt MRs? is issued on 
the standard output before the standard input is read; if the 
standard input is not a terminal, no prompt is issued. The 
MRS? prompt always precedes the comments? prompt (see 
-y keyletter). MRs in a list are separated by blanks and /or 
tab characters. An unescaped new-line character terminates 
the MR list. Note that if the v flag has a value [see 
admin(l)], it is taken to be the name of a program (or shell 



-n 



-glist 
-mlmrlist] 
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procedure) that will validate the correctness of the MR 
numbers. If a non«zero exit status is returned from the MR 
number validation program, delta terminates. (It is 
assumed that the MR numbers were not all valid.) 

-y[commentl Arbitrary text used to describe the reason for making the 
delta. A null string is considered a valid comment If ~y is 
not specified and the standard input is a terminal, the 
prompt CQitinents? is issued on the standard output before 
the standard input is read; if the standard input is not a ter- 
minal, no prompt is issued. An unescaped new-line charac- 
ter terminates the comment text. 

^ Causes delta to print (on the standard output) the SCCS 

file differences before and after the delta is applied in a 
dif f(l) format. 

FILES 

g-file Existed before the execution of delta; removed after comple- 

tion of delta. 

p-file Existed before the execution of delta; may exist after comple- 

tion of delta, 

q-file Created during the execution of delta; removed after comple- 

tion of delta. 

x-file Created during the execution of delta; renamed to SCCS file 

after completion of delta, 
z-file Created during the execution of delta; removed during the 

execution of delta. 

d-file Created during the execution of delta; removed after comple- 

tion of delta. 

Wif f Program to compute differences between the "gotten" file and 

the g-file, 

SEE ALSO 

admind), cdc(l), get(l), help(l), prsd), 3:indel(l), sccsf ile(4). 
bdif f (1) in the User'$ tUprmm Manual 

DIAGNOSTICS 

Use helpd) for explanations. 

NOTES 

A get of many S<ZCB fite* foUowed by a delta of those files^ shovild be avoided 
when the get generates a larg^ amount of data. Instead, multiple get/delta 
sequences should be used. 

If the standard input (-) is specified on the delta command line, the (if neces- 
sary) and -y l^eyletters must also be present. Omission of these keyletters causes 
an error. 

Comments are limited to text strings of at most 1024 characters. Line lengths 
gireater than 1000 characters cause undefined results. 
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NAME 

dis - object code disassembler 
SYNOPSIS 

dis [-o] [-V] [-L] [-s] [-d sec] [-D sec] [-F function] [-t sec] [-1 string] file ... 
DESCRIPTION 

The dis command produces an assembly language listing of file, which may be 
an object file or an archive of object files. Tlie listing includes assembly state- 
ments and an octal or hexadecimal representation of the binary that produced 
those statements. 

The following options are interpreted by the disassembler and may be specified in 
any order. 

-d sec Disassemble the named section as data, printing the offset of the 

data from the beginning of the section. 

-D sec Disassemble the named section as data, printing the actual address 

of the data. 

function Disassemble only the named ftmction in each object file specified on 
the command line. The -F option may be specified multiple times 
on the command line. 

Lookup source labels for subsequent printing. This option works 
only if the file was compiled with additional debugging information 
[e.g., the -g option of cc]. 

Disassemble the archive file specified by string. For example, one 
would issue the command dis -1 x -1 z to disassemble libx.a 
and libz.a, which are assumed to be in LIBDIR. 

Print numbers in octal. The default is hexadecimal. 

Perform symbolic disassembly where possible. Symbolic disassembly 
output will appear on the line following the instruction. Symbol 
names will be printed using G syntax. 

Disassemble the named section as text. 

Print, on standard error, the version number of the disassembler 
being executed. 

If the -d, or *t options are specified, only those named sections froiri each 
user-supplied file name will be disassembled. Otherwise, all sections containing 
text will be disassembled. 

On output, a number enclosed in brackets at the beginning of a line, such as [ 5 3 / 
indicates that the break-pointable line number starts with the following instruc- 
tion. These line nimibers will be prints only if the file was compiled with addi- 
tional debugging information [e.g., the --g option of ccj. An expression stich ^s 
<40> in the operand field or in the symbolic disassembly, following a relative dis- 
placement for control transfer instructions, is the computed address within the 
section to which control will be transferred. A function name will appear in the 
first column, followed by ( ) if the object file contains a symbol table. 



-1 string 

-o 
-s 

-t sec 
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FILES 



LIBDIR 



usually /usr/ccs/lib 



SEE ALSO 

as(l), cc(l), ld(l), a.out(4). 

DIAGNOSTICS 

The self-explanatory diagnostics indicate errors in the command line or problems 
encountered with the specified files. 



Since the -da option did not adhere to the command syntax rules, it has been 
replaced by -D. 

At this time, symbolic disassembly does not take advantage of additional infor- 
mation available if the file is compiled with the -g option. 



NOTES 
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NAME 

dimp - dump selected parts of an object file 

SYNOPSIS 

duirp [ options ] files 

DESCRIPTION 

The duirp command dumps selected parts of each of its object file arguments. 

This command will accept both object files and archives of object files. It 
processes each file argument according to one or more of the following options: 



-a Dump the archive header of each member of an archive. 

-C Dump decoded C++ symbol table names. 

-c Dump the string table(s). 

-D Dump debugging information. 

-f Dump each file header. 

-g Dump the global symbols in the symbol table of an archive, 

-h Dump the section headers. 

-L Dump dynamic linking information and static shared library infor- 
mation, if available. 

-1 Dump line number information. 

-o Dump each program execution header. 

-r Dump relocation information. 

-s Dump section contents in hexadecimal. 

-T index or -T indexl , index! 

Dump only the indexed symbol table entry defined by index or a 
range of entries defined by indexl , indexl. 

-t Dump symbol table entries. 

-u When reading a COFF object file, dump translates the file to ELF inter- 



nally (this translation does not affect the file contents). This option 
controls how much translation occurs from COFF values to ELF. 
Normally (without -u), the COFF values are preserved as much as 
possible, showing the actual bytes in the file. If -u is used, dump 
updates the values and completes the internal translation, giving a 
consistent ELF view of the contents. Although the bytes displayed 
under this option might not match the file itself, they show how the 
file would look if it were converted to ELF. (See cof2elf(l) for 
more information.) 

-V Print version information. 

The following modifiers are used in conjunction with the options listed above to 
modify their capabilities. 
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-^ number or '^ numberl,nutnber2 

Dump the section number indicated by number or the range of sec- 
tions starting at number! and ending # nmr&jerl. This modifier can 
be used wth -h, -s, and -r. When -d is used with -h or -s, the 
argument is treated as the number of a section or rangi <^ sections, 
When -d is used with -r, the argument is treated as the number of 
the section or range of sections to which the relocation applies. For 
example, to print out all relocation entries associated with the .text 
section, specify the number of the section as the argument to -d. If 
. text is section number 2 in the file, dump -d 2 will print all 
associated entries. To print out a specific relocation section use 
dunp -3 ~n name for raw data output, or dump -sv -n name for 
interpreted output. 

-n name Dump information pertaining only to the named entity. This 
modifier can be used with -h, -s, -r, and -t. When is used 
with ~h or -s, the argument will be treated as the name of a sec- 
tion. When -n is used with -t or -r, the argument will be treated 
as the name of a symbol. For example, dunp --t -n . text will 
dump the symbol t^le entry associated with the symbol whose 
name is .text, where duxrp -h -n .text will dump the section 
header information for the .text section. 

-p Suppress printing of the headings. 

-V Dump information in symbolic representation rather than numeric. 

This modifier can be used with -a (date, user id, group id), -f 
(class, data, type, machine, version, flags), -h (type, flags), -o (type, 
flags), -r (name, type), -s (interpret section contents wherever pos- 
sible), -t (type, bind), and -L (value). When -v is used with -s, all 
sections that can be interpreted, such as the string table or symbol 
table, wM l)e intetpreted, Ibr example, dunp -sv --n . symtab files 
will produce ^e same icramtted oi^tpiat as dunp -tv files, but 6mp 
-s .symtab fiks wffl prmt mm data in hexadecinpial. Without 
addiMonai modife^ duinp -sv files will dump all sections in the 
files interpreting all those that it can amd dumping the rest (such as 
. text or . data) as raw data. 

The dunp command attempts to format the information it dumps in a meaningful 
way, printing certain inforniaition in charactetv hescadecim^l, octal or decimal 
representation as appropriate. 

ALSO 

a . out(4)^ ar(i). 
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NAME 

get - get a version of an SCCS file 
SYNOPSIS 

get l-aseq-no.] [-ccuto^ l-ilist] [-rS/D] [-string] [-x/ist] [-l[p]] [-b] [-e] [-g] 
[-kl [-ml [-nl [-p] hsl [-tl file.., 

DESCRIPTION 

get generates an ASCII text file from each named SCCS file according to the 
specifications given by its keyletter arguments, which begin with The argu- 
ments may be specified in any order, but all keyletter arguments apply to all 
named SCCS files. If a directory is named, get behaves as though each file in the 
directory were specified as a named file, except that non-SCCS files (last com- 
ponent of the path name does not begin with s.) and imreadable files are 
silently ignored. If a name of - is given, the standard input is read; each line of 
the standard input is taken to be the name of an SCCS file to be processed. 

The generated text is normally written into a file called the g-file whose name is 
derived from the SCCS file name by simply removing the leading "s." (see also 
the FILES section below). 

Each of the keyletter arguments is explained below as though only one SCCS file 
is to be processed, but the effects of any keyletter argument apply independently 
to each named file. 

-rS/D The SCCS identification string (SID) of the version (delta) of an 
SCCS file to be retrieved. Table 1 below shows, for the most use- 
ful cases, what version of an SCCS file is retrieved (as well as the 
SID of the version to be eventually created by delta(l) if the -e 
keyletter is also used), as a function of the SID specified. 

"ccutoff Cutoff date-time, in the form: 

yy[MM[DD[HH{MM[SS]]]l] 

No changes (deltas) to the SCCS file that were created after the 
specified cutoff date-time are included in the generated ASQI text 
file. Units omitted from the date-time default to their maximum 
possible values; that is, -c7502 is equivalent to -c750228235959. 
Any number of non-numeric characters may separate the two- 
digit pieces of the cutoff date-time. This feature allows one to 
specify a cidoff date in the form: 

-c"77/2/2 9:22:25". 

-iXist A list of deltas to be included (forced to be applied) in the crea- 
tion of the generated file. The list has the following syntax: 

<list> ::= <range> I <list> , <range> 
<range> ::= SID I SID - SID 

SID, the SCCS Identification of a delta, may be in any form shown 
in the ''SID Specified" column of Table 1. 
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-xlist A list of deltas to be excluded in the creation of the generated file. 
See the -i keyletter for the list format. 

-e Indicates that the get is for the purpose of editing or making a 

change (delta) to the SCCS file via a subsequent use of delta(l). 
The -e keyletter used in a get for a particular version (SID) of the 
SCCS file prevents further gets for editing on the same SID until 
delta is executed or the j (joint edit) flag is set in the SCCS file 
[see admin(l)]. Concurrent use of get -e for different SIDs is 
always allowed. 

If the g-file generated by get with an -e keyletter is accidentally 
ruined in the process of editing it, it may be regenerated by re- 
executing the get command with the -k keyletter in place of the 
-e keyletter. 

SCCS file protection specified via the ceiling, floor, and authorized 
user list stored in the SCCS file [see admind)] are enforced when 
the -e keyletter is used. 

-b Used with the -e keyletter to indicate that the new delta should 

have an SID in a new branch as shown in Table 1. This keyletter 
is ignored if the b flag is not present in the file [see adxnin(l)] or if 
the retrieved delta is not a leaf delta. (A leaf delta is one that 
has no successors on the SCCS file tree.) A branch delta may 
always be created from a non-leaf delta. Partial SIDs are inter- 
preted as shown in the "SID Retrieved" column of Table 1. 

-k Suppresses replacement of identification keywords (see below) in 

the retrieved text by their value. The -k keyletter is implied by 
the -e keyletter. 

-l[pl Causes a delta summary to be written into an 1-file. If -Ip is 
used, then an 1-file is not created; the delta summary is written on 
the standard output instead. See IDENTIFICATION KEYWORDS 
for detailed information on the 1-file. 

-p Causes the text retrieved from the SCCS file to be written on the 

standard output. No g-file is created. All output that normally 
goes to the standard output goes to file descriptor 2 instead, 
unless the -s keyletter is used, in which case it disappears. 

-s Suppresses all output normally written on the standard output. 

However, fatal error messages (which always go to file descriptor 
2) remain unaffected. 

-m Causes each text line retrieved from the SCCS file to be preceded 

by the SID of the delta that inserted the text line in the SCCS file. 
The format is: SID, followed by a horizontal tab, followed by the 
text line. 

-n Causes each generated text line to be preceded with the %M% 

identification ke5rword value (see below). The format is: %M% 
value, followed by a horizontal tab, followed by the text line. 
When both the -m and -n keyletters are used, the format is: %M% 
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value, followed by a horizontal tab, followed by the -m keyletter 
generated format. 

-g Suppresses the actual retrieval of text from the SCCS file. It is pri- 

marily used to generate an 1-file, or to verify the existence of a 
particular SID. 

-t Used to access the most recently created delta in a given release 

(e.g., -rl), or release and level (e.g., -rl.2). 

-w string Substitute string for all occurrences of %W% when getting the fQe. 
Substitution occurs prior to keyword expansion. 

-aseq-no. The delta sequence number of the SCCS file delta (version) to be 
retrieved. This keyletter is used by the coirb command; it is not a 
generally useful keyletter. If both the -r and -a keyletters are 
specified, only the -a keyletter is used. Care should be taken 
when using the -a keyletter in conjunction with the -e keyletter, 
as the SID of the delta to be created may not be what one expects. 
The -r keyletter can be used with the -a and -e keyletters to con- 
trol the naming of the SID of the delta to be created. 

For each file processed, get responds (on the standard output) with the SID being 
accessed and with the number of lines retrieved from the SCCS file. 

If the -e keyletter is used, the SID of the delta to be made appears after the SID 
accessed and before the number of lines generated. If there is more than one 
named file or if a directory or standard input is named, each file name is printed 
(preceded by a new-line) before it is processed. If the -i keyletter is used, 
included deltas are listed following the notation "Included"; if the -x keyletter is 
used, excluded deltas are listed following the notation "Excluded". 
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TABLE 1. Determination of SCCS Identification String 



SID* 
Specified. 


Usedt 


Conditions 


SID 
Retrieved 


SID of Dplta 
\Ji. JL/eiici 

to be Created 


none^ 


no 


rv aeiauiis to mix 


tnl? ml 


ml? ^ml -L.1^ 

mix. vmL( +1^ 


nonet 


yes 


R defaults to mR 


mR.mL 


mR.mL.(mB-Hl).l 


R 


no 


K > mK 


mK.mL 




R 


no 


R = mR 


mR.mL 


mR.(mL+l) 


R 


yes 


R> mR 


mR.mL 


mR.mL.(mB+l).l 


R 


yes 


R = mR 


mR.mL 


mR.mL.(mB+l).l 


R 


— 


R < mR and 

R does not exist 


hR.mL** 


hR.mL.(mB+l).l 






Trimk succ.# 

Ill release ^ r\. 
and R pyists 


R TYlT 


JX.llll-t.vlllx7 1 ly. 1 


R.L 


no 




R.L 


R.(L+1) 


R.L 


yes 


Mr\ fT*iiriV Qiirr" 


R 1 

IX, Li 


JX.l-f.Vllli-' 1 1 /• l 


R.L 


— 


in release > R 


R.L 


R.L.(mB+l).l 


R.L.B 


no 


No branch succ. 


R.L.B.mS 


K.L.b.(mb+l) 


R.L.B 


yes 


No branch succ. 


R.L.B.mS 


R.L.(mB+l).l 


R.LB.S 


no 


No branch succ. 


R.L.B.S 


R.LB.(S+1) 


R.L.B.S 


yes 


No branch succ. 


R.L.B.S 


R.L.(mB+l).l 


R.L.B.S 




Branch succ. 


R.L.B.$ 


R.L.(mB+l).l 



* "R'', "L", "B", and "S^' are the "release", "level", "branch", and "sequence" 
components of the SID, respectively; "m" means "maximum". Thus, for 
example, "R.mL" means "the maximimi level number within release R"; 
"R.L.(mB+l).l" means "the first sequence number on the new branch (i.e., 
maximum branch number plus one) of level L within release R". Note that 
if the SID specified is of the form "R.L", "R.L.B", or "R.L.B.S", each of the 
specified components must exist. 

** 'liR" is the highest existing release that is lower than the specified, nonex- 
istent, release R. 

*** This is used to force creation of the first delta in a new release. 

# Successor. 

t The -b keyletter is effective only if the b flag [see admind)] is present in the 

file. An entry of - means "irrelevant". 
i This case applies if the d (default SID) flag is not present in the file. If the d 

flag is present in the file, then the SID obtained from the d flag is interpreted 

as if it had been specified on the command line. Thus, one of the other cases 

in this table applies. 

IDENTIFICATION KEYWORDS 

Identifying information is inserted into the text retrieved from the SCCS file by 
replacing identification ke)^ords with their value wherever they occur. The fol- 
lowing kejrwords may be used in the text stored in an SCCS file: 
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I&ywerd Value 

%M% Modtidei mme: either the valiiie of the m flag in the file [see adxnin(l>], 

or M absent, the^ naiwe' of the SCCS file^ with the Iteading a. removed, 
sees ideftli&ati«tti* (SW (%lt% . %L%.. %B% . %S%)^ of the retrieved text. 

lit Bf^cftv 

%S* Sequence. 

%0% Ctirrent date (YY/MM/DVy. 

%H* Current date (MM/DDprY): 

%m Current ^me {HH:MM:S$}\ 

Diite new^ese applied delta was crieated (YYiMMlDny). 

%Gt Date newest applied deifa was creaited (MM/DV/rr). 

W Time newest applied deta was created (HH;MM:SS). 

tYl Modulci type: rate of the t fliag, Itt the SCCS file [see adndnd)]. 

%r% SCCS fife name. 

Fully qwalified SCCS file narrtew 

The value of the q flag in the file [see admind)!. 

%^ Current line nuntber. This keyword is intended for identifying mes- 

sages output by the p^ogram^ such as> "this should not have hap- 
pened" type errors. It is tm bitended to be vised on every line to pro- 
vide sequence numbers. 

The four-charaaer string S it} recognisable by the what command. 
A shorthand ncrlation for constructing strings for UNIX System 
progmm files, « %Z%%m<tab>%i:% 
%JI% Another shorthand notation for constructing what strings for non- 
UNIX System program files: « %2%%Y% %M% %I%%z% 

Several auxiliary files may be created by get. These files are known generically 
as the g-file^ 1-file^ p-file, and z-file. The l^er before the hyphen is called the tag. 
Art auxiliary file name is formed from the SCCS file name: the last component of 
all sees file names must be of the form 8.modute*mme, the auxiliary files are 
named by replacing the leading d with the tag. The g-file is an exception to this 
scheme: the g-file is named by removing the s . prefix. For example, s . xyz . c, 
the auxiliary file names would be xyzj.c^ l^xyz.c, p.^^z.c, and z.xyz.c, 
respectively* 

The g-file, which contains the generated text, is created in the current directory 
(tmless the -p keyletter is used). A g-file is created in all cases, whether or not 
any lines of text were generated by the get. It is owned by the real user. If the 
-k keyletter is used or implied, its mode is 644; otherwise its mode is 444. Only 
the real user need have write permission in the current directory. 

The 1-file contains a table showing which deltas were applied in generating the 
retrieved text. The l*flle is created in the current directory if the -1 keyletter is 
used; its mode is 444 and it is owned by the real user. Only the real user need 
have write permission in the current directory. 
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Lines in the 1-file have the following format: 



a. A blank character if the delta was applied; * otherwise. 

b. A blank character if the delta was applied or was not applied and 
ignored; * if the delta was not applied and was not ignored. 

c. A code indicating a "special" reason why the delta was or was not 
applied: "I" (included), "X" (excluded), or "C" (cut off by a 
keyletter). 

d. Blank. 

e. sees identification (SID). 

f. Tab character. 

g. Date and time (in the form YYIMMIDD HH:MM:SS) of creation. 

h. Blank. 

i. Login name of person who created delta. 



The comments and MR data follow on subsequent lines, indented one hor- 
izontal tab character. A blank line terminates each entry. 

The p-file is used to pass information resulting from a get with an -e keyletter 
along to delta. Its contents are also used to prevent a subsequent execution of 
get with an -e keyletter for the same SID until delta is executed or the joint edit 
flag, j, [see admind)] is set in the sees file. The p-file is created in the directory 
containing the sees file and the effective user must have write permission in that 
directory. Its mode is 644 and it is owned by the effective user. The format of 
the p-file is: the gotten SID, followed by a blank, followed by the SID that the 
new delta will have when it is made, followed by a blank, followed by the login 
name of the real user, followed by a blank, followed by the date-time the get 
was executed, followed by a blank and the -i keyletter argument if it was 
present, followed by a blank and the -x keyletter argument if it was present, fol- 
lowed by a new-line. There can be an arbitrary number of lines in the p-file at 
any time; no two lines can have the same new delta SID. 

The z-file serves as a lock-out mechanism against simultaneous updates. Its con- 
tents are the binary (2 bytes) process ID of the command (i.e., get ) that created 
it. The z-file is created in the directory containing the SCCS file for the diiration 
of get. The same protection restrictions as those for the p-file apply for the z-file. 
The z-file is created with mode 444. 

FILES 

g-file Created by the execution of get. 

p-file [see delta(l)] 

q-file [see delta(l)] 

z-file [see delta(l)] 

bdif f Program to compute differences between the "gotten" file and 

the g-file. 

SEE ALSO 

admind), delta(l), helpd), prs(l), vrtiat(l). 
bdif f (1) in the User's Reference Manual 
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DIAGNOSTICS 

Use help(l) for explanations. 

NOTES 

If the effective user has write permission (either explicitly or implicitly) in the 
directory containing the SCCS files, but the real user does not, then only one file 
may be named when the -e keyletter is used. 
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NAME 

help - ask for help with message numbers or SCCS commands 

SYNOPSIS 

help [args] 

DESCRIPTION 

help finds information to explain a message from a command or explain the use 
of a SCCS command. Zero or more arguments may be supplied. If no argu- 
ments are given, help will prompt for one. 

The arguments may be either information within the parentheses following a 
message or SCCS command names. 

The response of the program will be the explanatory information related to the 
argument, if there is any. 

When all else fails, try "help stuck". 

FILES 

LIBDIR/help directory containing files of message text. 

LJBDIR/help/helploc file containing locations of help files not in 

LIBDIR/help, 

LIBDIR usually /usr/ccs/lib 
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NAME 

install - install commands 
SYNOPSIS 

/etc/install [-c dira] [-f dirb] [-i] [-n dire] [-m mode] [-u user] [-g group] [-o] 
[-s] fileldirx...] 

DESCRIPTION 

The install command is most commonly used in "makefiles" [see inake(l)] to 
install a file (updated target file) in a specific place within a file system. Each file 
is installed by cop5dng it into the appropriate directory, thereby retaining the 
mode and owner of the original command. The program prints messages telling 
the user exactly what files it is replacing or creating and where they are going. 

If no options or directories (dirx ...) are given, install will search a set of 
default directories (/bin, /usr/bin, /etc, /lib, and /usr/lib, in that order) for 
a fQe with the same name as file. When the first occurrence is found, install 
issues a message saying that it is overwriting that file with file, and proceeds to 
do so. If the file is not found, the program states this and exits without further 
action. 

If one or more directories (dirx . . .) are specified after file, those directories will 
be searched before the directories specified in the default list. 

The meanings of the options are: 



-c dira 



Installs a new command (file) in the directory specified by 
dira, only if it is not found. If it is found, install issues a 
message saying that the file already exists, and exits 
without overwriting it. May be used alone or with the -s 
option. 



-f dirb 



Forces file to be installed in given directory, whether or not 
one already exists. If the file being installed does not 
already exist, the mode and owner of the new file will be 
set to 755 and bin, respectively. If the file already exists, 
the mode and owner will be that of the already existing file. 
May be used alone or with the ~o or -s options. 



-i 



Ignores default directory list, searching only through the 
given directories (dirx . . .). May be used alone or with any 
other options except -c and -f . 



-n dire 



If file is not found in any of the searched directories, it is 
put in the directory specified in dire. The mode and owner 
of the new file will be set to 755 and bin, respectively. 
May be used alone or with any other options except -c and 
-f. 



-m mode 



The mode of the new file is set to mode. 



-u user 



The owner of the new file is set to user. 
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-g group The group id of the new file is set to group. Only available 
to the superuser. 

-o If file is found, this option saves the "found" file by copy- 

ing it to owfile in the directory in which it was found. This 
option is useful when installing a frequently used file such 
as /bin/sh^ where the existing file cannot b^ removed. 
May be used alone or with any other options except -c. 

-8 Suppresses printing of messages other than error messages. 

May be used alone or with any other options. 



SEE ALSO 

inake(l). 
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NAME 

Id " link editor for object files 

SYNOPSIS 

Id [options] files ... 

DESCRIPTION 

The Id command combines relocatable object files, performs relocation, and 
resolves external symbols. Relocatable object files given as arguments are com- 
bined to produce an executable object file, or, if the -r option is specified, relocat- 
able object files are combined to produce one relocatable object file. The output 
of Id is left in a. out by default. 

If any argument is a library, it is searched exactly once at the point it is encoun- 
tered in the argument list. Only those routines defining an imresolved external 
reference are loaded. The archive library symbol table [see ar(4)] is searched 
sequentially with as many passes as are necessary to resolve external references 
that can be satisfied by library members. Thus, the ordering of members in the 
library is functionally unimportant, unless there exist multiple library members 
defining the same external symbol. 

The following options are recognize by Id: 

-a Produce an executable object file; give errors for undefined references. 
This is the default behavior, -a may not be used with the -r option. 

-e qjsym 

Set the entry point address for the output file to be that of the symbol 
epsym. 

-Ix Search a library, lifeljc.a, the conventional name for archive libraries. A 
library is searched \vheh its name is encountered, so the placement of -1 
is significant. 

-m Produce a memory map or listing of the input/output sections on the 
standard output. 

-o outfile 

Produce an output object file named outfile. The name of the default 
object file is a. out. 

-r Combine relocatable object files to produce one relocatable object file. Id 
will not complain about unresolved references. This option cannot be 
used with -a. 

-s Strip symbolic information from the output file. The debug and line sfee- 
tions and their associated relocation entries will be removed. Except for 
relocatable files, the symbol table and string table sections will also be 
removed from the output object file. 

^t Turn off the warning about multiply defined symbols that are not the 
same size. 

-u symname 

Enter symname as an undefined symbol in the symbol table. This is useful 
for loading entirely from an archive library, since initially the symbol table 
is empty and an unresolved reference is needed to force the loading of the 
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first routine. The placement of this option on the con\mand line is 
significant; it must be placed before the library that will define the symbol. 

-L path 

Add path to the library search directories. Id searches for libraries first in 
any directories specified with -L options, then in the standard directories. 
This option is effective only if it precedes the -1 option on the command 
line. 

-^rmpfile 

Read mapfile as a text file of directives to Id. Because these directives 
change the shape of the output file created by Id, use of this option is 
strongly discouraged. 

-Q[y|n] 

Under -Qy, an ident string is added to the .conment section of the out- 
put file to identify the version of the link editor used to create the file. 
This will result in multiple Id idents when there have been multiple 
linking steps, such as when using Id -r. This is identical with the default 
action of the cc command. -Qn suppresses version. 

-V Output a message giving information about the version of Id being used. 

-X Generate a standard UNIX System file header within the "optional 
header" field in the output file. 

-YP, dirlist 

Change the default directories used for finding libraries, dirlist is a colon- 
separated path list. 

The environment variable LD_LIBRARY_PATH may be used to specify library 
search directories. In the most general case, it will contain two directory lists 
separated by a semicolon: 

dirlistl; dirlist! 

If Id is called with any number of occurences of -L, as in 

Id ... "Upathl ...-Ijpathn ... 
then the search path ordering is 

dirlistl pathl ... pathn dirlist! LIBPATH 

FILES 

libx.a libraries 
a. out output file 

LIBPATH usually /usr/ccs/lib : /lib : /usr/lib 

SEE ALSO 

as(l), cx:(l), exec(2), exit(2), end(3C), a.out(4), ar(4). 

The "C Compilation System" chapter and the "Mapfile Option" appendix in the 
Programmer's Guide: ANSI C and Programming Support Tools. 
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NOTES 

Through its options, the link editor gives users great flexibility; however, those 
who use the -M mapfile option must assume some added responsibilities. Use of 
this feature is strongly discouraged. 
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NAME 

lex ^ generate programs for simple lexical tasks 

SYNOPSIS 

leK[-c?tvn -V -Q[y|n]] [file] 

DESCRIPTION 

The lex command generates programs to be used in simple lexical analysis of 
text. 

The input files (standard input default) contain strings and expressions to be 
searched for and C text to be executed when these strings are found. 

lex generates a file named lex.yy.c. When lex.yy.c is compiled and linked 
with the lex library, it copies the input to the output except when a string 
specified in the file is found. When a specified string is found, then the 
corresponding program text is executed. The actual string matched is left in 
yytext, an external character array. Matching is done in order of the patterns in 
the file. The patterns may contain square brackets to indicate character classes, as 
in [abx-z] to indicate 3l, h, y, and z; and the operators *, +, and ? mean, 
respectively, any non-negative number of, any positive number of, and either zero 
or one occurrence of, the previous character or character class. Thus, [a^zA-Z] + 
matches a string of letters. The character . is the class of all ASCII characters 
except new-line. Parentheses for grouping and vertical bar for alternation are 
also supported. The notation r{d,e) in a rule indicates between d and e instances 
of regular expression r. It has higher precedence than | , but lower than *, ?, +, 
and concatenation. The character ^ at the beginning of an expression permits a 
successful match only immediately after a new-line, and the character $ at the 
end of an expression requires a trailing newJine, The character / in an express 
sion indicates trailing context; only the part of the expression up to the slash is 
returned in yytext, but the remainder of the expression must follow in the input 
stream. An operator character may be used as an ordinary symbol if it is within 
*^ symbols or preceded by \. 

Three macrqs are expected: input (> to read a character; \mput(c) to replace a 
character read; and output (c) to place an output character. They are defined in 
terms of the standard streams, but you can override them. The program gen- 
erated is named yylexO, and the lex library contains a mainO that calls it. The 
action REJECT on the right side of the rule causes this match to be rejected and 
the next suitable match executed; the function yymoreO accumulates additional 
characters into the same yytext; and the function yyless(n) pushes back 
yyleng -n characters into the input stream, (yyleng is an external int variable 
giving tl\e lengtti of ^text.) The macros input and output use files yyin and 
yyout to read from and write to, defaulted to stdin and atdout, respectively. 

Any line beginning with a blank is assumed to contain only C text and is copied; 
if it precedes %%, it is copied into the external definition area of the lex.yy.c file. 
AH rules should follow ^ %%, as in yacc. Lines preceding %% that begin with a 
rxon-blank character define the string on the left to be the remainder of the line; it 
can be called out later by surrounding it with {}. In this section, C code (and 
preprocessor statements) can also be included between %{ and %}. Note that 
curly brackets do not imply parentheses; only string substitution is done. 
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EXAMPLE 

D [0-9] 
%{ 

void 

skipconnrnts (void) 
{ 

for(;;) 
{ 

while (input 0 

if (input () = =V) 
return; 

else 

unput (yytext [yyleng-1] ) ; 

} 

} 

%} 

%% 

if printf("IF statement \n" ) ; 

[a-z] + print f ( "tag, value %s\n" , yytext) ; 

0{D}+ printf ("octal number %s\n" , yytext) ; 

{D}+ printf ("decimal number %s\n", yytext) ; 

"++" printf ( "unary op\n" ) ; 

"+" printf ( "binary op\n" ) ; 

"\n" ;/*no action */ 

" / * " skipcomnint s ( ) ; 

%% 

The external names generated by lex all begin with the prefix yy or YY. 

The flags must appear before any files. 

-c Indicates C actions and is the default. 

-t Causes the lex.yy.c program to be written instead to standard output. 

-V Provides a two-line summary of statistics. 

-n Will not print out the -v summary. 

-V Print out version information on standard error. 

-Q[y|n] Print out version information to output file lex.yy.c by using -Qy. 

The -Qn option does not print out version information and is the 
default. 

Multiple files are treated as a single file. If no files are specified, standard input 
is used. 

Certain default table sizes are too small for some users. The table sizes for the 
resulting finite state machine can be set in the definitions section: 
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%p n number of positions is n (default 2500) 

%n n number of states is n (500) 

%e n number of parse tree nodes is n (1000) 

%a n number of transitions is n (2000) 

%k n number of packed character classes is n (2500) 

%o n size of output array is n (3000) 

The use of one or more of the above automatically implies the -v option, unless 
the -n option is used. 

SEE ALSO 

yacc(l). 

The "lex" chapter in the Programmer's Guide: ANSI C and Programming Support 
Tools. 
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NAME 

lint - a C program checker 

SYNOPSIS 

lint [optidn$] files 

DESCRIPTION 

lint detects features of C program files which are likely to be bugs, non- 
portable, or wasteful. It also checks type usage more strictly than the compiler, 
lint issues error and warning messages. Among the things it detects are 
unreachable statements, loops not entered at the top, automatic variables declared 
and not used, and logical expressions whose value is constant, lint checks for 
functions that return values in some places and not in others, functions called 
with varying nimibers or types of arguments, and functions whose values are not 
used or whose values are used but none returned. 

Arguments whose names end with . c are taken to be C source files. Arguments 
whose names end with . In are taken to be the result of an earlier invocation of 
lint with either the -c or the -o option used. The .In files are analogous to .o 
(object) files that are produced by the cc(l) command when given a .c file as 
input. Files with other suffixes are warned about and ignored. 

lint takes aU the . c, . In, and lliJb-lx . In (specified by -Ix) files and processes 
them in their command line order. By default, lint appends the staindard C lint 
library (llib-lc.ln) to the end of the list of files. When the -c option is used, 
the .in and the lliib-ix.lri files atd ignored. When the -c option is not used, 
the second pass of lint checks the .In and the llib-lJc.ln list of files for 
mutual compatibility. 

Any number of lint options may be used, in any order, intermixed with file- 
name arguments. The following options are used to suppress certain kinds of 
complaints: 

-a Suppress complaints about assignments of long values to variables that 
are not long. 

-b Suppress complaints about break statements that cannot be reached. 

-h Do not apply heuristic tests that attempt to intuit bugs, improve style, and 
reduce waste. 

-m Suppress complaints about external symbols; that could be declared static. 

-u Suppress complaints about functions and external variables used and not 
defined, or defined and riot used. (This option is Suitable for running 
lint on a subset of files of i larger program). 

-V Sup^#es# coiTtpiaittts about unused arguments in fundions. 

-X Do not report variables referreci to by external declarations but never 
used. 

The following arguments alter lint's behavior: 

"iStf Se^rck fbt {ifeiiKfed Kesader files in the directory dir d§(&r€ s^fchiiig thi 
cmtiefrf direSdfy irtd/of the siiMwtd pMce: 
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-Ijc Include the lint library llib-lx.ln. For example, you can include a lint 
version of the math library llib-lm.ln by inserting -Im on the command 
line. This argument does not suppress the default use of llUb-lc.ln. 
These lint libraries must be in the assumed directory. This option can be 
used to reference local lint libraries and is useful in the development of 
multi-file projects. 

-Ldir Search for lint libraries in dir before searching the standard place. 

-n Do not check compatibility against the standard C lint library. 

-p Attempt to check portability to other dialects of C. Along with stricter 
checking, this option causes all non-external names to be truncated to 
eight characters and all external names to be truncated to six characters 
and one case. 

-s Produce one-line diagnostics only, lint occasionally buffers messages to 
produce a compound report. 

-k Alter the behavior of /*LINTED [message]*/ directives. Normally, lint 
will suppress warning messages for the code following these directives. 
Instead of suppressing the messages, lint prints an additional message 
containing the comment inside the directive. 

-y Specify that the file being linted will be treated as if the /*LINTLIBRARY*/ 
directive had been used. A lint library is normally created by using the 
/♦LINTLIBRARY*/ directive. 

-F Print pathnames of files, lint normally prints the filename without the 
path. 

-c Cause lint to produce a .In file for every .c file on the command line. 
These .In files are the product of lint's first pass only, and are not 
checked for inter-fimction compatibility. 

-ox Cause lint to create a lint library with the name llib-lx.ln. The -c 
option nullifies any use of the -o option. The lint library produced is the 
input that is given to lint's second pass. The -o option simply causes 
this file to be saved in the named lint library. To produce a llib-lx . In 
without extraneous messages, use of the -x option is suggested. The -v 
option is useful if the source file(s) for the lint library are just external 
interfaces. 

Some of the above settings are also available through the use of "lint com- 
ments" (see below). 

-V Write to standard error the product name and release. 
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-W/ik Write a . In file to file, for use by cf low(l). 
-Rfile Write a . In file to file, for use by cxref (1). 

lint recognizes many cc(l) command line options, including -D, -U, -g, -O, -Xt, 
-Xa, and -Xc, although -g and -O are ignored. Unrecognized options are warned 
about and ignored. The predefined macro lint is defined to allow certain ques- 
tionable code to be altered or removed for lint. Thus, the symbol lint should 
be thought of as a reserved word for all code that is planned to be checked by 
lint. 

Certain conventional comments in the C source will change the behavior of lint: 

/♦ARGSUSEDn*/ 

makes lint check only the first n arguments for usage; a missing 
n is taken to be 0 (this option acts like the -v option for the next 
fimction). 

/♦CONSTCOND*/ or /^CONSTANTCOND*/ or /*CONSTANTCONDITION*/ 
suppresses complaints about constant operands for the next 
expression. 

/♦EMPTY*/ 

suppresses complaints about a null statement consequent on an if 
statement. This directive should be placed after the test expres- 
sion, and before the semicolon. This directive is supplied to sup- 
port empty if statements when a valid else statement follows. It 
suppresses messages on an empty else consequent. 

/+FALLTHRU*/ or /*FALLTHROUGH*/ 

suppresses complaints about fall through to a case or default 
labelled statement. This directive should be placed immediately 
preceding the label. 

/♦LINTLIBRARY*/ 

at the beginning of a file shuts off complaints about unused func- 
tions and function arguments in this file. This is equivalent to 
using the -v and -x options. 

/♦LINTED [message]*/ 

suppresses any intra-file warning except those dealing with unused 
variables or functions. This directive should be placed on the line 
immediately preceding where the lint warning occurred. The -k 
option alters the way in which lint handles this directive. Instead 
of suppressing messages, lint will print an additional message, if 
any, contained in the comment. This directive is useful in conjunc- 
tion with the -s option for post-lint filtering. 

/♦NOTREACHED*/ 

at appropriate points stops comments about unreachable code. 
[This comment is typically placed just after calls to functions like 
exit(2)l. 
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/♦PRINTFLIKEn*/ 

makes lint check the first (n-1) arguments as usual. The nth 
argument is interpreted as a printf farmat string that is used to 
check the remaining arguments. 

/*PROTOLIBn*/ 

causes lint to treat function declaration prototypes as function 
definitions if n is non-zero. This directive can only be used in con- 
jimction with the 

/* LINTLIBRARY */ directive. If n is zero, function prototypes will 
be treated normally. 

/♦SCANFLIKEn*/ 

makes lint check the first (n-1) arguments as usual. The nth argu- 
ment is interpreted as a scanf format string that is used to check 
the remaining arguments. 

/♦VARARGSw*/ 

suppresses the usual checking for variable numbers of arguments 
in the following function declaration. The data types of the first n 
arguments are checked; a missing n is taken to be 0. The use of 
the ellipsis terminator (...) in the definition is suggested in new or 
updated code. 

lint produces its first output on a per-source-file basis. Complaints regarding 
included files are collected and printed after all source files have been processed, 
if ~s is not specified. Finally, if the -c option is not used, information gathered 
from all input files is collected and checked for consistency. At this point, if it is 
not clear whether a complaint stems from a given source file or from one of its 
included files, the source filename will be printed followed by a question mark. 

The behavior of the -c and the ~o options allows for incremental use of lint on 
a set of C source files. Generally, one invokes lint once for each source file with 
the -c option. Each of these invocations produces a . In file that corresponds to 
the .c file, and prints all messages that are about just that source file. After all 
the source files have been separately run through lint, it is invoked once more 
(without the -c option), listing all the . In files with the needed -Ijc options. This 
will print all the inter-file inconsistencies. This scheme works well with make; it 
allows make to be used to lint only the soured files that have bden Inodified 
since the last time the set of source files were linted. 

FILES 

LIBDIR the directory where the lint libraries specified by the -Ix 

option must exist 
L/BDIR/lint[12] first and second passed 

LJBD/R/ llib-ic . In declarations for C Library functions (binary format; source 

is in LJBDfR/llib-lc) 
L/BP^TH/llib-lm. In 

declarations fbr Math Library fimctions (binary format; 

source is in L/BDJR/llib-lm) 
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TMPDIR/*lint* 
TMPDIR 

LIBDIR 
LIBPATH 



temporaries 

usually /usr/tnp but can be redefined by setting the 
environment variable TMPDIR [see tenpnaxn in tmpnamOS)]. 
usually /ccs/lib 

usually /usr/ccs/lib:/lib:/usr/lib 



SEE ALSO 

cc(l), nake(l). 

See the "lint" chapter in the C Programmer's Guide: ANSI C and Programming Sup- 
port Tools. 
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NAME 

lorder - find ordering relation for an object library 

SYNOPSIS 

lorder file ... 

DESCRIPTION 

The input is one or more object or library archive files [see ar(l)]. The standard 
output is a list of pairs of object £Qe or archive member names; the first file of the 
pair refers to external identifiers defined in the second. The output may be pro- 
cessed by tsort(l) to find an ordering of a library suitable for one-pass access by 
Id. Note that the link editor Id is capable of multiple passes over an archive in 
the portable archive format [see ar(4)] and does not require that lorder be used 
when building an archive. The usage of the lorder command may, however, 
allow for a more efficient access of the archive during the link edit process. 

The following example builds a new library from existing . o files. 

ar -cr library 'lorder *.o I tsort' 

FILES 

TMPDIR/ *syinref temporary files 
TMPDIR/ *symdef temporary files 

TMPDIR usually /var/txcf> but can be redefined by setting the 

environment variable TMPDIR [see teirpnamC) in 
tirpndin(3S)]. 

SEE ALSO 

ar(l), ld(l), tsort(l), tenpnain(3S), tnpnameOS), ar(4). 

NOTES 

lorder will accept as input any object or archive file, regardless of its suffix, pro- 
vided there is more than one input file. If there is but a single input file, its suffix 
must be . o. 
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mUE 

Iprof ^ display line*bfy4ine execution count profile data 
SYNOPSIS 

Iprof [-rp] [-s] [-x] hi incdir] l-r srcfile] [-c cnf/ife] '[-^ prbgl [-^ 
Iprof ^ fikl.cttt ftteZ.cttt fileH.ctit [^] -d destfile.ctit 
DESCRri»TION 

Iprof reports the execution charactferistiGs of a iprogr^m on a (source) line by line 
basis. This is useful as a meahs to determine which iand how often portions of 
the code were exectited. 

Iprof interprets a profik file Xprog cnt by default) produced by ^the ^profiled pro- 
gram -prog (a. out by default), p-og creates a profile file if it has been loaded with 
the -ql option of cc. The profile information is computed fbr functions in a 
source file if the -ql option was used when the source file was compiled. 

By default, Iprof prints a listing of source files (th6 names of which are stored in 
the Sj^bol table of the executable file), with eadh line preceded by its line 
ituinber (in the source file) and th6 mirribdr of times the line was executed. 

The following <^ons may appear singly or be comtbined in any orto: 

-*p Print listing, eadi line preceded by the line number ahd the hiimber of 
times it was executed (default). This option can be use^ together %vith th6 
-s option to print both the source listing and summary information. 

-"s Prittt summary information of percentage of lines of code executed per 
function. 

Instead of printing the executioti Count numbers for each line, print each 
line preceded by its line number and a [Ul if the line was not executed. If 
the line was executed, print only the line number. 

^ inedir 

Look for source or header files in the directory incdir in addition to the 
current directory and the standard place for #include files (usually 
/usr/include). The user c^n specify mo^ than one directory by using 
lii^Mpte -^l options . 

-r srcfile 

Instead of printing all source files, print only those files named in -r 
options (to be used with the -p option *6My). l^ie ussa* ^an specify multi- 
ple files with a single -^r (q>tion. 

Use the file m^ph ii^<i ^f pr^ . as t!he inpu^ ipmfile file. 

prog 

Use the name of the program prdg instead of the name used when creating 
th6 .p-ofile tee. 6ecaufs^e ^he progmin nme stomi ift ti^ profile file con- 
tains tte pmh, kMs option is ttec^fssaQ^ if ^ €xecti^able file or 
|>^rofite fife lias hem iftovdi. 
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-V Print, on standard error, the version number of Iprof . 

Merging Data Files 

Iprof can also be used to merge profile files. The -m option must be accom- 
panied by the -d option: 

-m filel.cnt file2, cnt filen. cnt -d destfile ,cnt 

Merge the data files filel .cnt through filen .cnt by summing the execution 
counts per line, so that data from several runs can be accumulated. The 
result is written to destfile. cnt. The data files must contain profiling data 
for the same prog (see the -T option below). 

-T Time stamp override. Normally, the time stamps of the executable files 
being profiled are checked, and data files will not be merged if the time 
stamps do not match. If -T is specified, this check is skipped. 

CONTROLUNG THE RUN-TIME PROFILING ENVIRONMENT 

The environment variable PROFOPTS provides run-time control over profiling. 
When a profiled program (or shared object) is about to terminate, it examines the 
value of PROFOPTS to determine how the profiling data are to be handled. A ter- 
minating shared object will honor every PROFOPTS option except file^lename . 

The environment variable PROFOPTS is a comma-separated list of options inter- 
preted by the program being profiled. If PROFOPTS is not defined in the environ- 
ment, then the default action is taken: The profiling data are saved in a file (with 
the default name, prog, cnt) in the current directory. If PROFOPTS is set to the 
null string, no profiling data are saved. The following are the available options: 

xnsg=[y|n] 

If msg=y is specified, a message stating that profile data are being saved is 
printed to stderr. If rnsg=n is specified, only the profiling error messages 
are printed. The default is msg=y. 

merge=[y|nl 

If merge=y is specified, the data files will be merged after successive runs. 
If merge=n is specified, the data files are not merged after successive runs, 
and the data file is overwritten after each execution. The merge will fail if 
the program has been recompiled, and the data file will be left in TMPDIR. 
The default is inerge=n. 

pid=[y|n] 

If pid=y is specified, the name of the data file will include the process ID 
of the profiled program. Inclusion of the process ID allows for the crea- 
tion of different data files for programs calling fork. If pid=n is specified, 
the default name is used. The default is pid=n. For Iprof to generate its 
profiling report, the -c option must be specified with Iprof otherwise the 
default will fail. 

dir=dimame 

The data file is placed in the directory dimame if this option is specified. 
Otherwise, the data file is created in the directory that is current at the 
end of execution. 
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file^lename 

filename is used as the name of the data file in dir created by the profiled 
program if this option is specified. Otherwise, the default name is used. 
For Iprof to generate its profiling report, the -c option must be specified 
with Iprof if the file option has been used at execution time; otherwise 
the default will fail. 

FILES 

prog, cnt profile data 

TMPDIR usually /usr/tirp but can be redefined by setting the environment 
variable TMPDIR [see tempnam in txnpnain(3S)]. 

SEE ALSO 

cc(l), prof (1), f ork(2), titpnam(3S). 

The "Iprof" chapter in the Programmer's Guide: ANSI C and Programming Support 
Tools. 

NOTES 

For the -m option, if destfile .cnt exists, its previous contents are destroyed. 

Optimized code cannot be profiled; if both optimization and line profiling are 
requested, profiling has precedence. 

Different parts of one line of a source file may be executed different numbers of 
times (e.g., the for loop below); the count corresponds to the first part of the line. 

For example, in the following for loop 

mainO 
1 [2] { 

int j; 

1 [5] for (j =0; j < 5; 

5 [6] sub(j); 

1 [8] } 

sub (a) 
int a; 
5 [12] { 

5 [13] printf("a is %d\n", a) ; 

5 [14] } 

line 5 consists of three parts. The line count listed, however, is for the initializa- 
tion part, that is, j = 0. 
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NAME 

m4 - macro processor 

SYNOPSIS 

m4 [options] [files] 

DESCRIPTION 

The m4 command is a macro processor intended as a front end for C, assembler, 
and other languages. Each of the argument files is processed in order; if there are 
no files, or if a file name is the standard input is read. The processed text is 
written on the standard output. 

The options and their effects are as follows: 

-e Operate interactively. Interrupts are ignored and the output is unbuf- 
fered. 

-s Enable line s)mc output for the C preprocessor (#line . . . ) 

"Bint Change the size of the push-back and argument collection buffers from 
the default of 4,096. 

-Hint Change the size of the s)mibol table hash array from the default of 199. 
The size should be prime. 

-Sint Change the size of the call stack from the default of 100 slots. Macros 
take three slots, and non-macro arguments take one. 

-Tint Change the size of the token buffer from the default of 512 bytes. 

To be effective, the above flags must appear before any file names and before any 
-D or ~u flags: 

-Dnamei^al] 

Defines name to val or to null in vaVs absence. 

-Vname 

undefines name. 

Macro calls have the form: 

name{argl/irg2, . . ., argn) 

The ( must immediately follow the name of the macro. If the name of a defined 
macro is not followed by a (, it is deemed to be a call of that macro with no 
argtiments. Potential macro names consist of alphanumeric characters and under- 
score (_), where the first character is not a digit. 

Leading unquoted blanks, tabs, and new-lines are ignored while collecting argu- 
ments. Left and right single quotes are used to quote strings. The value of a 
quoted string is the string stripped of the quotes. 

When a macro name is recognized, its arguments are collected by searching for a 
matching right parenthesis. If fewer arguments are supplied than are in the 
macro definition, the trailing arguments are taken to be null. Macro evaluation 
proceeds normally during the collection of the arguments, and any commas or 
right parentheses that happen to turn up within the value of a nested call are as 
effective as those in the original input text. After argument collection, the value 
of the macro is pushed back onto the input stream and rescanned. 
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m4 makes available the following built-in macros. These macros may be 
redefined, but once this is done the original meaning is lost. Their values are null 
unless otherwise stated. 

define the second argimient is installed as the value of the macro whose 
name is the first argument. Each occurrence of $n in the replace- 
ment text, where n is a digit, is replaced by the n-th argument. 
Argimient 0 is the name of the macro; missing arguments are 
replaced by the null string; $# is replaced by the number of argu- 
ments; $* is replaced by a list of all the arguments separated by 
commas; $@ is like $*, but each argument is quoted (with the 
current quotes). 

undef ine removes the definition of the macro named in its argument. 

defn returns the quoted definition of its argument(s). It is useful for 

renaming macros, especially built-ins. 

pushdef like define, but saves any previous definition. 

popdef removes current definition of its argimient(s), exposing the previ- 
ous one, if any. 

if def if the first argument is defined, the value is the second argument, 

otherwise the third. If there is no third argument, the value is null. 
The word unix is predefined. 

shift returns all but its first argument. The other arguments are quoted 

and pushed back with commas in between. The quoting nullifies 
the effect of the extra scan that will subsequently be performed. 

changequote 

change quote s)mibols to the first and second arguments. The sym- 
bols may be up to five characters long, changequote without 
arguments restores the original values (i.e., ^ ^ ). 

changecom change left and right comment markers from the default # and 
new-line. With no arguments, the comment mechanism is effec- 
tively disabled. With one argument, the left marker becomes the 
argument and the right marker becomes new-line. With two argu- 
ments, both markers are affected. Comment markers may be up to 
five characters long. 

divert m4 maintains 10 output streams, numbered 0-9. The final output is 
the concatenation of the streams in numerical order; initially stream 
0 is the current stream. The divert macro changes the current 
output stream to its (digit-string) argument. Output diverted to a 
stream other than 0 through 9 is discarded. 

undivert causes immediate output of text from diversions named as argu- 
ments, or all diversions if no argtiment. Text may be imdiverted 
into another diversion. Undiverting discards the diverted text. 
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divnisn 
dnl 

ifelse 

incr 

deer 
eval 



len 
index 

substr 

translit 

include 
sinclude 

syscand 

sysval 
maketenp 

iiv4exit 

m4wrap 



returns the value of the current output stream. 

reads and discards characters up to and including the next new- 
line. 

has three or more arguments. If the first argument is the same 
string as the second, then the value is the third argument. If not, 
and if there are more than four arguments, the process is repeated 
with arguments 4, 5, 6 and 7. Otherwise, the value is either the 
fourth string, or, if it is not present, null. 

returns the value of its argument incremented by 1. The value of 
the argument is calculated by interpreting an initial digit-string as a 
decimal number. 

returns the value of its argument decremented by 1. 

evaluates its argument as an arithmetic expression, using 32-bit 
arithmetic. Operators include +, -, *, /,%,** (exponentiation), bit- 
wise &, I, and relationals; parentheses. Octal and hex 
numbers may be specified as in C. The second argument specifies 
the radix for the result; the default is 10. The third argument may 
be used to specify the minimum number of digits in the result. 

returns the number of characters in its argument. 

returns the position in its first argument where the second argu- 
ment begins (zero origin), or -1 if the second argument does not 
occur. 

returns a substring of its first argument. The second argument is a 
zero origin number selecting the first character; the third argument 
indicates the length of the substring. A missing third argument is 
taken to be large enough to extend to the end of the first string. 

transliterates the characters in its first argument from the set given 
by the second argument to the set given by the third. No abbrevia- 
tions are permitted. 

returns the contents of the file named in the argument. 

is identical to include, except that it says nothing if the file is inac- 
cessible. 

executes the UNIX System command given in the first argument. 
No value is returned. 

is the return code from the last call to syscmd. 

fills in a string of XXXXX in its argument with the current process 
ID. 

causes immediate exit from m4. Argument 1, if given, is the exit 
code; the default is 0. 

argument 1 will be pushed back at final EOF; example: 
m4wrap ( ^ cleanup () ^ ) 
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errprint 
dunpdef 

traceon 

traoeoff 



SEE ALSO 

as(l), cc(l). 



prints its argument on the diagnostic output file. 

prints current names and definitions, for the named items, or for all 
if no arguments are given. 

with no arguments, turns on tracing for all macros (including 
built-ins). C5therwise, turns on tracing for named macros. 

turns off trace globally and for any macros specified. Macros 
specifically traced by traceon can be tmtraced only by specific 
calls to traoeoff. 
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nmim 

make - maintain, update, and regenerate groups of programs 
SYNOPS^IS 

make [-f mak^le] [-eiknpqrst] [names} 
DESCRIPTION 

make allows the programmer to maintain, update, and regenerate groups of com- 
puter programs, make executes commands in makefile to update one or more tar- 
get names (names are typically programs). If the -f option is not present, then 
makefile. Makefile, and the Source Code Control System (SCCS) files 
s. makefile, and s. Makefile are tried in order. If makefile is -, the standard 
input is taken. More than one -f makefile argument pair may appear. 

make updates a target only if its dependents are newer than the target. All prere- 
quisite files of a target are added recursively to the list of targets. Missing files 
are deemed to be outdated. 

The following list of four directives can be included in makefile to extend the 
options provided by make. They are used in makefile as if they were targets: 

.tJEFAULT: If a file must be made but there are no explicit commands or 
relevant built-in rules, the commands associated with the name 
. DEFAULT are used if it exists. 

. I(^ORE : Same effect as the -i option. 

.PRECIOUS: Dependents of the .PRECIOUS entry will not be removed when 
quit or interrupt are hit. 

. SIliENT : Same effect as the -s option. 

The options for make are listed below: 

-e Environment variables override assignments within makefiles. 

*f makefile Description filename (makefile is assumed to be the name of a 
description file). 

^i Ignore error codes returned by invoked commands. 

*k Abandon work on the current entry if it fails, but continue on 

other branches that do not depend on that entry. 

*n No execute mode. Print commands, but do not execute them. 

Even command lines beginning with an 8 are printed. 

-p Print out the complete set of macro definitions and target 

descriptions. 

^ Question, make returns a zero or non-zero status code depend- 

ing on whether or not the target file has been updated. 

Do not use the built-in rules. 

^0 Silent mode* Do not print command lines before executing. 

-t Touch the target files (causing them to be updated) rather than 

issue the usual commands. 
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Creating the makefile 

The makefile invoked with the -f option is a carefully structured file of explicit 
instructions for updating and regenerating programs, and contains a sequence of 
entries that specify dependencies. The first line of an entry is a blank-separated, 
non-null list of targets, then a :, then a (possibly null) list of prerequisite files or 
dependencies. Text following a ; and all following lines that begin with a tab are 
shell commands to be executed to update the target. The first non-empty line 
that does not begin with»a tab or # begins a new dependency or macro definition. 
Shell commands may be continued across lines with a backslash-new-line (\ 
new-line) sequence. Everything printed by make (except the initial tab) is passed 
directly to the shell as is. Thus, 

echo a\ 
b 

will produce 
ab 

exactly the same as the shell would. 

Sharp (#) and new-line surroimd comments including contained \ new-line 
sequences. 

The following makefile says that pgm depends on two files a . o and b . o, and that 
they in turn depend on their corresponding source files (a.c and b.c) and a com- 
mon file incl.h: 

P9in: a.o b.o 

cc a.o b.o -o pgm 

a. o: incl.h a.c 

cc -c a.c 

b. o: incl.h b.c 

cc -c b.c 

Command lines are executed one at a time, each by its own shell. The SHELL 
environment variable can be used to specify which shell make should use to exe- 
cute commands. The default is /bin/sh. The first one or two characters in a 
command can be the following: @, @-, or -@. If @ is present, printing of the 
command is suppressed. If - is present, make ignores an error. A line is printed 
when it is executed unless the -s option is present, or the entry .SILENT: is 
included in makefile, or imless the initial character sequence contains a @. The -n 
option specifies printing without execution; however, if the command line has the 
string $(MAKE) in it, the line is always executed (see the discussion of the 
MAKEFLAGS macro in the "Environment" section below). The -t (touch) option 
updates the modified date of a file without executing any commands. 

Commands returning non-zero status normally terminate make. If the -i option 
is present, if the entry . IGNORE : is included in makefile, or if the initial character 
sequence of the command contains the error is ignored. If the -k option is 
present, work is abandoned on the current entry, but continues on other branches 
that do not depend on that entry. 
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Interrupt and quit cause the target to be deleted unless the target is a dependent 
of the directive .PRECIOUS. 

Environment 

The environment is read by make. All variables are assumed to be macro 
definitions and are processed as such. The environment variables are processed 
before any makefile and after the internal rules; thus, macro assignments in a 
makefile override environment variables. The -e option causes the environment 
to override the macro assignments in a makefile. Suffixes and their associated 
rules in the makefile will override any identical suffixes in the built-in rules. 

The MAKEFLAGS environment variable is processed by make as containing any 
legal input option (except ~f and -p) defined for the command line. Further, 
upon invocation, make "invents" the variable if it is not in the environment, puts 
the current options into it, and passes it on to invocations of commands. Thus, 
MAKEFLAGS always contains the current input options. This feature proves very 
useful for "super-makes". In fact, as noted above, when the -n option is used, 
the command $ (MAKE) is executed anyway; hence, one can perform a make -n 
recursively on a whole software system to see what would have been executed. 
This result is possible because the -n is put in MAKEFLAGS and passed to further 
invocations of $ (MAKE) . This usage is one way of debugging all of the makefiles 
for a software project without actually doing anything. 

Include Files 

If the string include appears as the first seven letters of a line in a makefile, and 
is followed by a blank or a tab, the rest of the line is assumed to be a filename 
and will be read by the current invocation, after substituting for any macros. 

Macros 

Entries of the form stringl = string! are macro definitions, string! is defined as 
all characters up to a comment character or an unescaped new-line. Subsequent 
appearances of $(stringll:substl=lsuhst2]]) are replaced by stringl. The 
parentheses are optional if a single-character macro name is used and there is no 
substitute sequence. The optional :substl =subst2 is a substitute sequence. If it is 
specified, all non-overlapping occurrences of substl in the named macro are 
replaced by substl . Strings (for the purposes of this type of substitution) are del- 
imited by blanks, tabs, new-line characters, and beginnings of lines. An example 
of the use of the substitute sequence is shown in the "Libraries" section below. 

Internal Macros 

There are five internally maintained macros that are useful for writing rules for 
building targets. 

$* The macro $* stands for the filename part of the current dependent with the 
suffix deleted. It is evaluated only for inference rules. 

$@ The $0 macro stands for the full target name of the current target. It is 
evaluated only for explicitly named dependencies. 

$< The $< macro is only evaluated for inference rules or the . DEFAULT rule. It 
is the module that is outdated with respect to the target (the "manufac- 
tured" dependent file name). Thus, in the .c.o rule, the $< macro would 
evaluate to the . c file. An example for making optimized . o files from . c 
files is: 
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•c.o: 

cc -c -0 $* . c 

.c.o: 

cc -c -6 $< 

$? The $? macro is evaluated when explicit rules from the makefile are 
evaluated. It is the list of pieregpisites that are outdated with respect to the 
tai^gety and essentially those modules that must be rebuilt. 

$% The $% macro is only evaluated when the target is an archive library 
member of the form lib (file, o) . In this case, $@ evaluates to lib and $% 
evaluates to the library member/ file. 6. 

Four of the five macros can have alternative forms. When ah upper case D or F is 
appended to any of the four macros, the meaning is changed to "directory part" 
for D and "file part" for F. Thus, $(@D) refers to the directory part of the string 
$@. If there is no directory part, . / is generated. The only macro excluded from 
this alternative form is $?. 

Suffixes 

Certain names (for instance, those ending with .o) have inferable prerequisites 
such as .c, .s, etc. If no update commands for such a file appear in makefile , dLwd 
if an inferable prerequisite exists, that prerequisite is compiled to make the target. 
In this case, make has inference rules that allow building files from other files by 
examining the suffixes and determining an appropriate inference rule to use. The 
current default inference rules are: 



.c 




.f 


.f- 


.s 




.sh 


.sh- 


.C 


.c- 


.c.a 


.CO 


.c-.a 


.c-.c 


.c^.o 


.f .a 


.f .o 


.f-.a 


.f-.f 


.f-.o 


.h-.h 


.l.c 


.l.o 


.l-.c 


.l-.l 


.l-.o 


.s.a 


.s.o 


.s-.a 


. s- . o 


. s*^ . s 


. sh- . sh 


.y.c 


.y.o 


.y-.c 


.y-.o 




.C.a 


.Co 


.C-.a 


.C-.C 


.C- .o 


.L.C 


.L.o 


.L-.C 


.L-.L 


.L-.O 


.Y.C 


.Y.o 


.Y-.C 


.Y-.O 


.Y-.Y 



















The internal rules for make are contained in the source file rules , c for the make 
program. These rules can be locally modified. To print out the rules compiled 
into th6 make on any machine in a form suitable for recompilation, the following 
command is used: 

make -pf - 2>/de^)^/^tuli </dev/hull 

A tilde in the above rules refers to an SCCS file [see sccsf ile(4)]. Thus, the rule 
.c-.o would transform an SCCS C source file into an object file (.o). Because the 
s . of the SCCS files is a prefix, it is incompatible with the make suffix point of 
view. Hence, the tilde is a way of changing any file reference into an SCCS file 
reference. 

A rule with only one Suffix (tor example, .c:) is the defintlibh of h6W to build x 
from jc.c. In effect, the other suffix is null. This featuf^ is useful for building 
targets from only one soui'ce file, fot &tmif\e, shell procedures and simple C pro- 
grams. 
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Additional suffixes are given as the dependency list for .SUFFIXES. Order is 
significant: the first possible name for which both a file and a rule exist is inferred 
as a prerequisite. The default list is: 

.SUFFIXES: .o .c .c*^ .y .y** ,1 .l*^ .s .S'*' .sh .sh-^ .h .h-* .f .f*^ .C 

Here again, the above command for printing the internal rules mil display the list 
of suffixes implemented on the current machine. Multiple suffix lists acaimulate; 
.$WFXXES: with no dependencies clears the list of suffixes. 

The first example can be doiie more briefly. 

PC ffc.p b.o -p pgm 
a.o b.q; incl.h 

This abbreviation is possible because make has a set of internal rules for building 
files. The user may add rules to this list by simply putting them in the makefile. 

Certain macros are used by the default inference rules to permit thie inclusion of 
optional matter in any resulting commands. For example^ CFLAGS, LFIA6S, and 
YFLAGS are used for compiler options to cc(l), lex(l), and yacc(l), respectively. 
Again, the previous method for examining the current rules is recommended. 

The inference of prerequisites can be controlled. The rule to create a file with 
suffix .o from a file with suffix .c is specified as an entry with .c.o: as the tar- 
get and no dependents. Shell commands associated with the target define the 
rule for making a . o file from a . c file. Any target that has no slashes in it and 
starts with a dot is identified as a rule and npt a true target. 

Libraries 

If a target or dependency name contains parentheses^ it is assumed to be an 
archive library, the string within parentheses referring to a member within the 
library. Thus, lib(file.o) and $(LIB) <file.o) both refer to an archive library 
that contains file . o. (This example assumes the LIB macro has been previously 
defined.) The expression $ (LIB) (filel.o fiXe2.o) is not legal. Rules pertain- 
ing to archive libraries have the form .XX. a where the XX is the suffix from 
which the archive member is to be made. An unfortimate by-product of the 
current implementation requires the XX to be different from the suffix of the 
archive member. Thus, one cannot have lib ( file. o) depend upon file.o 
explicitly. The most c;pn>inon use of the archive interface follows. Here, we 
assume the source Sfiles are all C type source: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 
Secho lib is now i:5>-to-dat:e 

,G.a: 

m .-f $*.p 
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In fact, the .c.a rule listed above is built into make and is unnecessary in this 
example. A more interesting, but more limited example of an archive library 
maintenance construction follows: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 
$(CC) -c $(CFLAGS) $(?:.o=.c) 
$(AR) $(ARFLAGS) lib $? 
rm $? 

@echo lib is now up-to-date 
.c.a: ; 

Here the substitution mode of the macro expansions is used. The $? list is 
defined to be the set of object filenames (inside lib) whose C source files are out- 
dated. The substitution mode translates the .o to .c. (Unfortunately, one cannot 
as yet transform to .c-^; however, this transformation may become possible in the 
future.) Also note the disabling of the .c.a: rule, which would have created 
each object file, one by one. This particular construct speeds up archive library 
maintenance considerably. This type of construct becomes very cumbersome if 
the archive library contains a mix of assembly programs and C programs. 

FILES 

[Mm] akef ile and s . [Mm] akef ile 
/bin/sh 

SEE ALSO 

cc(l), lex(l), yacc(l), printf (3S), sccsf ile(4). 
cd(l), slid) in the User's Reference Manual 

See the "make" chapter in the Programmer's Guide: ANSI C and Programming Sup- 
port Tools. 

NOTES 

Some commands return non-zero status inappropriately; use -i or the - com- 
mand line prefix to overcome the difficulty. 

Filenames with the characters = : @ will not work. Commands that are directly 
executed by the shell, notably cd(l), are ineffectual across new-lines in make. The 
syntax lib(filel.o file2.o fileS.o) is illegal. You cannot build 
lib (file, o) from file.o. 
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NAME 

mcs - manipulate the comment section of an object file. 
SYNOPSIS 

mcs [-a string] [-c] [-d] [-n name] [-p] [-V] file ... 
DESCRIPTION 

The mcs command is used to manipulate a section, by default the .coniiient sec- 
tion, in an ELF object file. It is used to add to, delete, print, and compress the 
contents of a section in an ELF object file, and only print the contents of a section 
in a COFF object file, mcs must be given one or more of the options described 
below. It applies each of the options in order to each file. 

The following options are available. 

-a string 

Append string to the comment section of the ELF object files. If string 
contains embedded blanks, it must be enclosed in quotation marks. 

-c Compress the contents of the comment section of the ELF object files. All 
duplicate entries are removed. The ordering of the remaining entries is 
not disturbed. 

-d Delete the contents of the comment section from the ELF object files. The 
section header for the comment section is also removed. 

-n name 

Specify the name of the comment section to access if other than . conment. 
By default, mcs deals with the section named .comnent. This option can 
be used to specify another section. 

-p Print the contents of the comment section on the standard output. Each 
section printed is tagged by the name of the file from which it was 
extracted, using the format filename {member jiame] : for archive files; and 
filename : for other files. 

-V Print, on standard error, the version number of mcs. 

If the input file is an archive [see ar(4)], the archive is treated as a set of indivi- 
dual files. For example, if the -a option is specified, the string is appended to the 
comment section of each ELF object file in the archive; if the archive member is 
not an ELF object file, then it is left unchanged. 

If mcs is executed on an archive file the archive symbol table will be removed, 
unless only the -p option has been specified. The archive symbol table must be 
restored by executing the ar command with the -s option before the archive can 
be linked by the Id command, mcs will produce appropriate warning messages 
when this situation arises. 

EXAMPLES 

mcs -p file # Print file's coitment section 

mcs -a string file # impend string to file's comment section 
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mm 

TMPDIR/m^ temporary files 

TMPIMR usually /usr/tmp but can be redefined by setting the 

environment variable ^H^IE |see t^nipnaittC) in 

$ii mm 

ardX asdX ccdX tinpnain(3SX a.out(4), ar(4). 

See the -'Object File§^' chapter in Progmmrm'^ GM^ki ANSI C Programming 

WC0 cannot add to^ delete or compress the contents of a section th^t is contained 
within a segment. 
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SYNOPSIS 

rrtdritibl [ -^6 0Utfile] infik 

DESCRIPTidN 

ih6ri^ cdmmkM iitptst ^ specifeatidn ifile, iHfihe^ thSt ;de^cfi6es ^Ke 

^bffiiattirig conVeihSidnfe for htiiii^fic quantities (mdSletary aftd dtHerwi^iB) fdr a 
specific locale. 

-o oUifile Write the otttptit on outpte; otherwise. Write the 6iitput on a file 

T^he butput of is stiitable for use hy the ld<iaiecdnv( ) fttnctibn (see 

localfeconv(3C) ) . Before outfile ckh be used by localec6ny< ), it must be 
ihstalled in the /xxsx/lih/lxsc^l^llotale directory with the h^me LC_MONETARY by 
someone who is siiper-uSer or a member of group bin. locale ife the locale whose 
numeric fbrhiattihg cbhVehliiOfts are described ih ihfile, this fQe must be Readable 
by user, group, kfid dther; itb t)ther pefmife^lbhs l&hbuld be 6et. use formatting 
convehtibiiS for ttSitfte^c qfuilitities described ih this file, set the LCJdONE'TARY 
cfriviitJitm^ vKi^^Ie afjipfbprikteiiy ^riviroh(5) br Setlbcal^OO). 

Once instilled, this file will be used by the Ibc^leconvO function to initialize a 
structtu^e of type, ^trfiidt IcdftV. for a descri^on t)f ^h field in this structure, 
see ibcaleconv(3C) . 

Struct Idofiv { 

char *deciitaljpbint; /* "." */ 

char *thbiisan<is_^4^>; /* "" (z^rb !tferi#dfi striii^i ^/ 

chat '^^bi:^fA#; /* ^/ 

tMt ;^ihtJc6rt_^yi&o!L; A V 

char *currikicy_synibol ; /* '*/ 

char *itdhjaeciinal_^bint; /* */ 

char *nb'A_thous^s__^ep; /* ^/ 

char *ift6h__cp:ouping; /* */ 

char *positive^si^; /* "" */ 

char *'neg¥tivej5i9n; /* */ 

char int^fracjligitis; /'* CHAR_MAX */ 

char frac_digits; /* CHARJdAX */ 

char ^JcB_prece^es; /* Cffi^^MAX */ 

char p£S<^J>y^space; /* CHARJ4AX */ 

ciiar csjprecedes; /* CHMMyiAX */ 

dhar hjsfepj^y^space'; /* cMkjMAX */ 

char p__signjposn; /*'cffiR_MAX */ 

c^r tij5ignj>bsn; /* cri^aTilAX */ 



The specification file contains the value each struct Iconv member should be 
set to, except for ^he first two m^bers, decimal jpoint and thousands jep which are 
set by the LC_NUMERIC category to setlocale(3C). Each member's value is given 
on a separate line and in the order listed in the struct Iconv definition above. 
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Lines starting with a # are taken to be comments and are ignored. All other lines 
are assumed to describe their corresponding structure member. A blank line 
describes the null string for structure members that are pointers to strings. A 
character in a string may be in octal or hex representation. For example, \141 or 
\x61 could be used to represent the letter 'a'. 

Given below is an example of what the specification file for Italy would look like: 

# Italy 
3 

ITL. 
L. 

\3 



0 
0 
1 
0 
1 
0 
1 
1 

Note that the first non-comment line in the specification file describes the group- 
ing field. 

FILES 

/lib/locale//ocafe/LC_MDNETARY 

LC__M)NETARY database for locale 

/usr/ lib/ locale/C/montbl jC 

input file used to construct LC__MONETARY in the default locale. 

SEE ALSO 

localeconv(3C), setlocale(3C) in the Programmer's Reference Manual. 
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NAME 

nm - print name list of an object file 

SYNOPSIS 

nm [ -oxhvnefurplVT ] files 

DESCRIPTION 

The nm command displays the symbol table of each ELF or COFF object file, 
specified by file(s). The file may be a relocatable or absolute ELF or COFF object 
file; or it may be an archive of relocatable or absolute ELF or COFF object files. 
For each symbol, the following information will be printed: 

Index The index of the symbol. (The index appears in brackets.) 

Value The value of the sjonbol is one of the following: a section offset for 
defined sjnnbols in a relocatable file; alignment constraints for symbols 
whose section index is SHNjCOMMON; a virtual address in executable and 
dynamic library files. 

Size The size in bytes of the associated object. 

Type A symbol is of one of the following types: NOTYPE (no type was 
specified), OBJECT (a data object such as an array or variable), FUNC (a 
function or other executable code), SECTION (a section symbol), or FILE 
(name of the source file). 

Bind The symbol's binding attributes. LOCAL symbols have a scope limited 
to the object file containing their definition; GLOBAL symbols are visible 
to all object files being combined; and WEAK symbols are essentially glo- 
bal symbols with a lower precedence than GLOBAL. 

Other A field reserved for future use, currently containing 0. 

Shndx Except for three special values, this is the section header table index in 
relation to which the symbol is defined. The following special values 
exist: ABS indicates the symbol's value will not change through reloca- 
tion; COMMON indicates an unallocated block and the value provides 
alignment constraints; and UNDEF indicates an undefined symbol. 

Name The name of the symbol. 

The output of nm may be controlled using the following options: 

-o Print the value and size of a symbol in octal instead of decimal. 

-X Print the value and size of a S5mibol in hexadecimal instead of decimal. 

-h Do not display the output heading data. 

-V Sort external symbols by value before they are printed. 

-n Sort external symbols by name before they are printed. 

-e See NOTES below. 

~f See NOTES below. 

-u Print undefined s5anbols only. 
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-r Prepend the name af the object file or archive to each output line. 

-p Produce easily parsable, terse output. Each symbol name is preceded 

by its value (blanks if undefined) and one of the letters U (undefined), N 
(symbol has no type), D (data object symbol), T (text symbol), S (section 
symbol), or F (file symbol). If the symbol's binding attribute is LOCAL, 
the key letter is lower case; if the symbol's binding attribute i$ WEAI^ 
the key letter is upper case; if the -1 modifier is specified, the upper 
case key letter is followed by a *; if the s)anbors binding attribute is 
GJJOBAL, the key letter is upper case. 

-1 Distinguish between WEAK and GLOBAL S)niibols by appending a * to the 

key letter for WEAK symbols. 

-V Print the version of the nm command executing on the standard error 

output, 

-T See NOTES below. 

Options may be used in any order, either singly or in combination, and may 
appear anywhere in the command line. When conflicting options are specified 
(such as nm -V -n) the first is taken and the second ignored with a warning mes- 
sage to the user. 

SiE ALSO 

as(l), cc(l), duxipd), ld(l), a.out(4), ar(4). 

NOTES 

The following options are obsolete because of changes to the object file format 
and will be deleted in a future release. 

--e Print only external and static symbols. The symbol table now contains 

only static and external symbols. Automatic symbols no longer appear 
in the symbol table. They do appear in the debugging information pro- 
duced by cc -g, which may be examined using duiT|>(l). 

Produce full output. Redundant symbols (such as .text, .data, etc), 
which existed previously do not exist and producing fidl output will be 
identical to the default output. 

By default, nm prints the entire name of the symbols listed. Since sym- 
bol name? h^ve been inpv^ to the last column, the problem of 
overflow is removed and it is np Ipngfir fiece^^s^ to truncate the sym- 
bol n^^. 
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NAME 

prof - display profile data 
SYNOPSIS 

prof [-t I c I a I n] [-0 I x] [-^ I 1] [-z] [-h] [-s] l-m mdata] -Vlprog] 
DESCRIPTION 

The prof command interprets a profile file produced by the monitor fimction. 
The symbol table in the object file prog (a . out by default) is read and correlated 
with a profile file (mon.out by default). For each external text symbol the percen- 
tage of time spent executing between the address of that symbol and the address 
of the next is printed, together with the number of times that function was called 
and the average number of milliseconds per call. 

The mutually exclusive options -t, -c, -a, and -n determine the type of sorting 
of the output lines: 

-t Sort by decreasing percentage of total time (default), 
-c Sort by decreasing number of calls, 
-a Sort by increasing symbol address, 
-n Sort lexically by symlx)l name. 

The mutually exclusive options -o and -x specify the printing of the address of 
each symbol monitored: 

-o Print each symbol address (in octal) along with the s)mibol name. 

-X Print each symbol address (in hexadecimal) along with the symbol name. 

The mutually exclusive options -g and -1 control the type of symbols to be 
reported. The -1 option must be used with care; it applies the time spent in a 
static function to the preceding (in memory) global function, instead of giving the 
static function a separate entry in the report. If all static functions are properly 
located (see example below), this feature can be very useful. If not, the restilting 
report may be misleading. 

Assume that A and B are global functions and only A calls static function S. If S 
is located immediately after A in the source code (that is, if S is properly 
located), then, with the -1 option, the amount of time spent in A can easily be 
determined^ including the time spent in S. If, however, both A and B call S, 
then, if the -1 option is used, the report will be misleading; the time spent dur- 
ing B's call to S will be attributed to A, making it appear as if more time had 
been spent in A than really had. In this case, function S cannot be properly 
located. 

•^g Include static (non-global) functions. 

-1 Do not include static (non-global) functions (default)* 

The following options may be used in any combination: 

«i Include all symbols in the profile mnge, even if associated with zero 

number of calls and zero time. 



10/89 



Page 1 



prof{1) 



prof(1) 



-h Suppress the heading normally printed on the report. (This is useful 

if the report is to be processed further.) 

-s Print a summary of several of the monitoring parameters and statistics 

on the standard error output. 

-m mdata Use file mdata instead of xnon . out as the input profile file. 

~V Print prof version information on the standard error output. 

A program creates a profile file if it has been link edited with the -p option of 
cc. This option to the cc command arranges for calls to monitor at the begin- 
ning and end of execution. The call to monitor at the end of execution causes 
the system to write a profile file. The number of calls to a fimction is tallied if 
the -p option was used when the file containing the function was compiled. 

The name of the file created by a profiled program is controlled by the environ- 
mental variable PROFDIR. If PROFDIR is not set, mon.out is produced in the 
directory current when the program terminates. If ?ROFDlR=string, 
string/pid .progname is produced, where progname consists of argv[0] with any 
path prefix removed, and pid is the process ID of the program. If PROFDIR is set, 
but null, no profiling output are produced. 

A single function may be split into subfunctions for profiling by means of the 
MARK macro [see prof (5)]. 

FILES 

xnon . out default profile file 

a . out default namelist (object) file 

SEE ALSO 

cc(l), Iprof (1), exit(2), prof il(2), monitorOC), prof (5). 

The "Iprof" chapter in the Programmer's Guide: ANSI C and Programming Support 
Tools. 

NOTES 

The times reported in successive identical runs may show variamces because of 
varying cache-hit ratios that result from sharing the cache with other processes. 
Even if a program seems to be the only one using the machine, hidden back- 
ground or asynchronous processes may blur the data. In rare cases, the clock 
ticks initiating recording of the program counter may "beat" with loops in a pro- 
gram, grossly distorting measurements. Call counts are always recorded pre- 
cisely, however. 

Only programs that call exit or return from main are guaranteed to produce a 
profile file, unless a final call to monitor is explicitly coded. 

The times for static functions are attributed to the preceding external text symbol 
if the -g option is not used. However, the call counts for the preceding function 
are still correct; that is, the static function call counts are not added to the call 
counts of the external function. 

If more than one of the options -t, -c, -a, and -n is specified, the last option 
specified is used and the user is warned. 
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NAME 

prs - print an SCCS file 
SYNOPSIS 

prs [-dldataspec]] [-r[S/D]l [-e] [-1] l-cldate-time]] [-a] files 
DESCRIPTION 

prs prints, on the standard output, parts or all of an SCCS file [see sccsf ile(4)] 
in a user-supplied format. If a directory is named, prs prints the files in that 
directory, except the non-SCCS files (last component of the path name does not 
begin with s.) and imreadable files. If a name of - is given, the standard input 
is read; each line of the standard input is taken to be the name of an SCCS file or 
directory to be processed, prs silently ignores non-SCCS files and imreadable 
files. 

Arguments to prs, which may appear in any order, consist of keyletter argu- 
ments and file names. 

The keyletter arguments apply independently to each named file: 

-dldataspec] Specifies the output data specification. The dataspec is a 
string consisting of SCCS file data keywords (see the DATA 
KEYWORDS section) interspersed with optional user- 
supplied text. 

-r[S/D] Specifies the SCCS identification (SID) string of a delta for 

which information is desired. The default is the top delta. 

-e Requests information for all deltas created earlier than and 

including the delta designated via the -r keyletter or the 
date given by the -c option. 

-1 Requests information for all deltas created later than and 

including the delta designated via the -r keyletter or the 
date given by the -c option. 

"oldaie-time] The cutoff date- time in the form: 

YY[MM{DD[HH[MM[SS\m 

Units omitted from the date- time default to their max- 
imum possible values; for example, -c7502 is equivalent to 
-C750228235959. Any number of non-numeric characters 
may separate the fields of the cutoff date; for example, 
"-C77/2/2 9:22:25". 

-a Requests printing of information for both removed, i.e., 

delta type = R, [see rmdeld)] and existing, i.e., delta type = 
D, deltas. If the -a keyletter is not specified, information 
for existing deltas only is provided. 

DATA KEYWORDS 

Data keywords specify those parts of an SCCS file that are to be retrieved and 
output. All parts of an SCCS file [see sccsf ile(4)] have an associated data key- 
word. There is no limit on the number of times a data keyword may appear in a 
dataspec. 
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The information printed by prs consists of: (1) the user-supplied text; and (2) 
appropriate values (extracted from the SCCS file) substituted for the recognized 
data keywords in the order of appearance in the dataspec. The format of a data 
keyword value is either "Simple" (S), in which keyword substitution is direct, or 
"Multi-line" (M), in which keyword substitution is followed by a carriage return. 

User-supplied text is any text other than recognized data ke5words. A tab is 
specified by \t and carriage return /new-line is specified by \n. The default data 
keywords are: 

":Dt:\t:DL:\nME^:\n:MR:CCM1ENTS:\n:C:" 



Keyword Data Item 

: Dt : Delta information 

:DL: Delta line statistics 

: Li : Lines inserted by Delta 

:Ld: Lines deleted by Delta 

:Lu: Lines unchanged by Delta 

:DT: Delta type 

:I: SCCS ID string (SID) 

: R : Release number 

:L: Level number 

:B: Branch number 

: S : Sequence number 

:D : Date Delta created 

:Dy: Year Delta created 

:Dm: Month Delta created 

:Dd: Day Delta created 

: T : Time Delta created 

:Th: Hour Delta created 

:Tm: Minutes Delta created 

: Ts : Seconds Delta created 

:P: Programmer who created Delta 

: DS : Delta sequence number 

:DP: Predecessor Delta seq-no. 

:DI : Seq-no. of deltas incL, excl., ignored 

:Dn : Deltas included (seq #) 

:Dx: Deltas excluded (seq #) 

:Dg: Deltas ignored (seq #) 

:MR: MR numbers for delta 

:C: Comments for delta 

:UN: User names 

:FL: Flag list 



File Section Value Format 

Delta Table See below* S 

:Li:/:Ld:/:Lu: S 

" nnnnn S 

nnnnn S 

nnnnn S 

D or R S 

:R:.:L:.:B:.:S: S 

nnnn S 

nnnn S 

" nnnn S 

nnnn S 

:Dy:/:Dm:/:Dd: S 

nn S 

nn S 

nn S 

:Th: : :Tm: : :Ts: S 

nn S 

nn S 

nn S 

" logname S 

nnnn S 

nnnn S 

:Dn:/:Dx:/:Dg: S 

:DS: :DS:... S 

:DS: :DS:... S 

:DS: :DS:... S 

text M 

text M 

User Names text M 

Flags text M 
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jyword Data Item 


File Section 


Value 


Format 


: Y: 




ti 


text 


S 


•ME** 


iVi^ VcUlUctilviri Xldg 




yes or no 


S 


:MP : 


MR validation pgni name 


If 


16X1 


c 


:KF: 


Keyword error/warning flag 




yes or no 


s 


:KV: 


Keyword validation string 


M 


text 


s 


:BF: 


Branch flag 


If 


yes or no 


s 


:J: 


Joint edit flag 




yes or no 


s 


:LK: 


Locked releases 


II 


:R: ... 


s 


:Q: 


User-defined keyword 




text 


s 


:M: 


Module name 




text 


s 


:FB: 


Floor boundary 


If 


:R: 


b 


:CB: 


Ceiling boundary 




:R: 


s 


. US . 


L^rauii OLU 


II 


: I : 


c 


:ND: 


Null delta flag 


If 


ves or no 


s 


:FD: 


File descriptive text 


Comments 


text 


M 


:BD: 


Body 


Bodv 


text 


M 


:GB: 


Gotten body 


ft 


text 


M 


:W: 


A form of what(l) string 


N/A 


:Z::M:\t::I: 


s 


:A: 


A form of what(l) string 


KT / A. 
N/A 




:Z: S 


:Z: 


what(l) string delimiter 


N/A 


@(#) 


S 


:F: 


sees file name 


N/A 


text 


S 


:PN: 


sees file path name 


N/A 


text 


S 




* :Dt: = :DT: :I: 


:D: :T: :P: :DS 


: :DP: 





EXAMPLES 

The command 

prs ^"Users eind/or user IDs for :F: are:\n:UN:" s.file 

may produce on the standard output: 

Users and/or user IDs for s.file are: 

xyz 

131 

abc 

The command 

prs -d"Newest delta for pgm :M: : :I: Created :D: By :P:" -r 
s.file 

may produce on the standard output: 

Newest delta for pgm xnain.c: 3.7 Created 77/12/1 By cas 
The default case; 

prs s.file 
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produces on the standard output: 

D 1.1 11/12/1 00:00:00 cas 1 000000/00000/00000 
MRs: 

bl78-12345 
bl79~54321 

cc»m:nts: 

this is the conment line for s.file initial delta 

for each delta table entry of the "D" type. The only keyletter argument allowed 
to be used with the "special case" is the -a keyletter. 

FILES 

/usr/ tiip/pr ? ? ? ? ? 
SEE ALSO 

admin(l), delta(l), getdX help(l), sccsf ile(4). 

DIAGNOSTICS 

Use help(l) for explanations. 
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regcnp - regular expression compile 

SYNOPSIS 

regcnp [-] file... 
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DESCRIPTION 

The regcnp command performs a fimction similar to regcnp and, in most cases, 
precludes the need for calling regcnp from C programs. Bypassing regcnp saves 
on both execution time and program size. The command regcnp compiles the 
regular expressions in file and places the output in file . i. If the - option is used, 
the output is placed in file . c. The format of entries in file is a name (C variable) 
followed by one or more blanks followed by one or more regular expressions 
enclosed in double quotes. The output of regcnp is C source code. Compiled 
regular expressions are represented as extern char vectors, file . i files may thus 
be #included in C programs, or file.c files may be compiled and later loaded. 
In the C program that uses the regcnp output, regex(abc, line) applies the reg- 
ular expression named abc to line. Diagnostics are self-explanatory. 

EXAMPLES 

name " ( [A-Za-z] [A-Za-z0-9_] *) $0" 

telno "\({0,l}([2-9] [01] [1-9])$0\){0,1} *" 
"([2-9] [0-9]{2})$l[ -]{0,1}" 
"([0-9] {4}) $2" 

The three arguments to telno shown above must all be entered on one line. 
In the C program that uses the regcnp output, 

regex (telno, line, area, exch, rest) 
applies the regular expression named telno to line. 

SEE ALSO 

regcnp(3G). 
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NAME 

rmdel - remove a delta from an SCCS file 

SYNOPSIS 

rmdel -rS/D files 

DESCRIPTION 

rmdel removes the delta specified by the SID (SCCS identification string) from 
each named SCCS file. The delta to be removed must be the newest (most recent) 
delta in its branch in the delta chain of each named SCCS file. In addition, the 
delta specified must not be that of a version being edited for the purpose of mak- 
ing a delta; that is, if a p-file exists for the named SCCS file [see get(l)], the delta 
specified must not appear in any entry of the p-file. 

The -r option specifies the SID level of the delta to be removed. 

If a directory is named, rmdel behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and unreadable files are silently ignored. If a 
name of - is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed; non-SCCS files and unread- 
able files are silently ignored. 

The rules governing the removal of a delta are as follows: if you make a delta 
and have appropriate file permissions, you can remove it; if you own the file and 
directory in which a new delta file resides, you can remove the delta. 

FILES 

x.file [See delta(l)] 
z.file [See delta(l)] 

SEE ALSO 

deltad), get(l), help(l), prs(l), sccsf ile(4). 

DIAGNOSTICS 

Use help(l) for explanations. 
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NAME 

sact - print current SCCS file editing activity 

SYNOPSIS 

sact files 

DESCRIPTION 

sact informs the user of any impending deltas to a named SCCS file. This situa- 
tion occurs when get with the -e option has been previously executed without a 
subsequent execution of delta. If a directory is named on the command line, 
sact behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files and imreadable files are silently ignored. If a name of 
- is given, the standard input is read with each line being taken as the name of 
an SCCS file to be processed. 

The output for each named file consists of five fields separated by spaces. 

Field 1 specifies the SID of a delta that currently exists in the SCCS file 
to which changes will be made to make the new delta. 

Field 2 specifies the SID for the new delta to be created. 

Field 3 contains the logname of the user who will make the delta (i.e., 
executed a get for editing). 

Field 4 contains the date that get -e was executed. 

Field 5 contains the time that get -e was executed. 

SEE ALSO 

delta(l), dif f(l), get(l), help(l), unget(l). 

DIAGNOSTICS 

Use help(l) for explanations. 
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NAME 



sccsdif f - compare two versions of an SCCS file 

SYNOPSIS 

sccsdif f -rSIDl -rSlDl [-p] [-sn] files 

DESCRIPTION 

sccsdif f compares two versions of an SCCS file and generates the differences 
between the two versions. Any number of SCCS files may be specified, but argu- 
ments apply to all files. 



-rSlDl -rSIDZ 



SIDl and S/D2 specify the deltas of an SCCS file that are 
to be compared. Versions are passed to bdif f in the 
order given. 



-sn 



pipe output for each file through pr. 

n is the file segment size that bdif f will pass to dif f . 
This option is useful when dif f fails due to a high sys- 
tem load. 



FILES 



/usr/txrp/get????? 



temporary files 



SEE ALSO 



get(l), help(l). 

dif f(l), bdif f(l), pr(l) in th^ User's Reference Manual 
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NAME 

sdb - symbolic debugger 
SYNOPSIS 

sdb [-e] [-S signo] [-V] [-W] [-w] lobjfile [corfile [directoiy-list]]] 
DESCRIPTION 

sdb is the symbolic debugger for C and assembly programs, sdb may be used to 
examine executable program files and core files. It may also be used to examine 
live processes in a controlled execution environment. 

The objfile argument is the name of an executable program file. To take full 
advantage of the symbolic capabilities of sdb, this file should be compiled with 
the -g (debug) option. If it has not been compiled with the -g option, the sym- 
bolic capabilities of sdb will be limited, but the file can still be examined and the 
program debugged. 

The corfile argument is the name of a core image file. A core image file is pro- 
duced by the abnormal termination of objfile or by the use of gcore. A core 
image file contains a copy of the segments of a program. The default for corfile is 
core. A core image file need not be present to use sdb. Using a hyphen (-) 
instead of corfile forces sdb to ignore an existing core image file. 

The directory-list argument is a colon-separated list of directories that is used by 
sdb to locate source files used to build objfile. If no directory list is specified, sdb 
will look in the current directory. 

The following options are recognized by sdb: 

-e Ignore symbolic information and treat nonsymbolic addresses as file 
offsets. 

-s signo 

Where signo is a decimal number that corresponds to a signal number [see 
signal(2)], do not stop live processes under control of sdb that receive 
the signal. This option may be used more than once on the sdb command 
line. 

-V Print version information. If no objfile argument is specified on the com- 
mand line, sdb will exit after printing the version information. 

-W Suppress warnings about corfile being older than objfile or about source 
files that are older than objfile. 

-w Allow user to write to objfile or corfile. 

sdb recognizes a current line and a current file. When sdb is examining an exe- 
cutable program file without a core file, the current line and current file are ini- 
tially set to the line and file containing the first line of main. If corfile exists, then 
current line and current file are initially set to the line and file containing the 
source statement where the process terminated. The current line and current file 
change automatically as a live process executes. They may also be changed with 
the source file examination commands. 
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Names of variables are written as in C, Variables local to a procedure may be 
accessed using the ifbrm procedure ivarmMe. If no procedure name is given, the 
procedure containing the current line is used by default. 

Structure members may be referred to as variable .member, pointers to structxire 
members as variable->member, and array elements as vartableinumber] . Pointers 
may also be dereferenced by using the form pointer [number}. Combinations of 
these forms may also be used. The form number''>member may be used where 
number is the address of a pointer, and number , member where number is inter^ 
preted as the address of a structure instance. The template of the structure type 
used in this case will be the last structure type referenced. When sdb displays 
the value of a structure, it does so by displaying the value of all elements of the 
structure. The address of a structure is displayed by displaying the address of 
the structure instance rather than the addresses of individual elements. 

Elements of a multidimensional array may be referred to as variable 
[number] [number]..., or as variable [number , number, ...]. In place of number, the 
form number; number may be used to indicate a range of values, * may be used to 
indicate all legitimate values for that subscript, or subscripts may be omitted 
entirely if they are the last subscripts and the full range of values is desired. If 
no subscripts are specified, sdb will display the value or all elements of the array. 

A particular instance of a variable on the stack is referred to as 
procedure '.variable, number. The number is the occurrence of the specified pro- 
cedure on the stack, with the topmost occurrence being 1. The default procedtire 
is the one containing the current line. 

Addresses may be used in sdb commands as well. Addresses are specified by 
decimal, octal, or hexadecimal numbers. 

Line numbers in the source program are specified by the form filename -.number or 
procedure -.number. In either case, the number is relative to the beginning of the file 
and corresponds to the line number used by text editors or the output of pr, A 
number used by itself implies a line in the current file. 

While a live process is running under sdb, all addresses and identifiers refer to 
the live process. When sdb is not examining a live process, the addresses and 
identifiers refer to objfile or corfile. 

Commands 

The commands for examining data in the program are: 

t Prints a stack trace of the terminated or halted program. The function 
invoked most recently is at the top of the stack. For C programs, the stack 
ends with _start, which is the startup routine that invokes main. 

T Prints the top line of the stack trace. 

variable/clm 

Print the value of variable according to length / and format m. The numeric 
count c indicates that a region of memory, beginning at the address implied 
by variable, is to be displayed. The length specifiers are: 
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b one byte 

h two bytes (half word) 

1 four bytes (long word) 

Legal values for m are: 
c character 
d signed decimal 
u unsigned decimal 

0 octal 

X hexadecimal 

f 32-bit single precision floating point 
g 64-bit double precision floating point 

s Assumes that variable is a string pointer and prints characters start- 
ing at the address pointed to by the variable. 

a Prints characters starting at the variable's address. Do not use this 
with register variables. 

p pointer to procedure 

1 Disassembles machine-language instruction with addresses printed 
numerically and sjmibolically. 

I Disassembles machine-language instruction with addresses printed 
numerically only. 

Length specifiers are effective with formats c, d, u, o, x. The length specifier 
determines the output length of the value to be displayed. This value may 
be truncated. The count specifier c displays that many units of memory, 
starting at the address of the variable. The number of bytes in the unit of 
memory is determined by / or by the size associated with the variable. If the 
specifiers c, I, and m are omitted, sdb uses defaults. If a count specifier is 
used with the s or a command, then that many characters are printed. Oth- 
erwise, successive characters are printed until either a null byte is reached 
or 128 characters are printed. The last variable may be redisplayed with the 
. / command. 

For a limited form of pattern matching, use the sh metacharacters * and ? 
within procedure and variable names, (sdb does not accept these metachar- 
acters in file names, as the fimction name in a line number when setting a 
breakpoint, in the fimction call command, or as the argument to the e com- 
mand.) If no procedure name is supplied, sdb matches both local and glo- 
bal variables. If the procedure name is specified, then sdb matches only 
local variables. To match global variables only, use : pattern. To print all 
variables, use *:*. 
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linenumber7lm 
variable I llm 

Prints the value at the address from the executable or text space given by 
linenumber or variable (procedure name), according to the format Im. The 
default format is i. 

variable=lm 

linenumber=lm 

number^lm 

Prints the address of variable or linenumber, or the value of number. I specifies 
length and m specifies the format. If no format is specified, then sdb uses 
Ix (four-byte hex), m allows you to convert between decimal, octal, and 
hexadecimal. 

variable ! value 

Sets variable to the given value. The value may be a number, a character 
constant, or a variable. The value must be well-defined; structures are 
allowed only if assigning to another structure variable of the same type. 
Character constants are denoted ^character. Numbers are viewed as integers 
unless a decimal point or exponent is used. In this case, they are treated as 
having the type double. Registers, except the floating point registers, are 
viewed as integers. Register names are identical to those used by the assem- 
bler (for example, hregname where regname is the name of a register). If the 
address of a variable is given, it is regarded as the address of a variable of 
type int. C conventions are used in any type conversions necessary to per- 
form the indicated assignment. 

X Prints the machine registers and the current machine-language instruction. 

X Prints the current machine-language instruction. 

The commands for examining source files are: 

e 

e procedure 
e filename 
e directory/ 

e, without arguments, prints the name of the current file. The second form 
sets the current file to the file containing the procedure. The third form sets 
the current file to filename. The current line is set to the first line in the 
named procedure or file. Source files are assumed to be in the directories in 
the directory list. The fourth form adds directory to the end of the directory 
list. 

/regular expression/ 

Searches forward from the current line for a line containing a string match- 
ing regular expression, as in ed. The trailing / may be omitted, except when 
associated with a breakpoint. 

7 regular expression! 

Searches backward from the current line for a line containing a string 
matching regular expression, as in ed. The trailing ? may be omitted, except 
when associated with a brecikpoint. 
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p Prints the current line. 

z Prints the current line and the following nine lines. Sets the current line to 
the last line printed. 

w Prints the 10 lines (the window) around the current line. 

number 

Specifies the current line. Prints the new current line. 
count-^ 

Advances the current line by count lines. Prints the new current line. 

count- 
Resets the current line by count lines back. Prints the new current line. 



The commands for controlling the execution of the source program are: 

count r args 
count R 

Runs the program with the given arguments. The r command with no 
arguments reuses the previous arguments to the program. The R command 
nms the program with no arguments. An argument beginning with < or > 
redirects the standard input or output, respectively. Full sh syntax is 
accepted. If count is given, it specifies the number of breakpoints to be 
ignored. 

linenumber c count 
linenumber C count 

Continues execution, sdb stops when it encoimters count breakpoints. The 
signal that stopped the program is reactivated with the C command and 
ignored with the c command. If a line number is specified, then a tem- 
porary breakpoint is placed at the line and execution continues. The break- 
point is deleted when the command finishes. 

linenumber g count 

Continues with execution resumed at the given line. If count is given, it 
specifies the number of breakpoints to be ignored. 

s count 
S count 

3 single steps the program through count lines or if no count is given, then 
the program runs for one line, s will step from one function into a called 
function. S also steps a program, but it will not step into a called function. 
It steps over the function called. 

i count 
I count 

Single steps by count machine-language instructions. The signal that caused 
the program to stop is reactivated with the I command and ignored with 
the i command. 
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variable$m count 
address :m count 

Single steps (as with s) until the specified location is modified with a new 
value. If count is omitted, it is, in effect, infinity. Variable must be accessible 
from the current procedure. TTiis command can be very slow. 

level V 

Toggles verbose mode. This is for use when single stepping with S, s, or nt 
If leoel is omitted, then just the current source file and /or function name is 
printed when either changes. If level is 1 or greater, each C source line is 
printed before it executes. If level is 2 or greater, each assembler statement 
is also printed. A v turns verbose mode otf. 

k Kills the program being debugged. 

procedure {argl/irgi,..,) 

procedure (argl/irgl,...) /m 

Executes the named procedure with the given arguments. Arguments can 
be register names, integer, character, or string constants, or names of vari- 
ables accessible from the current procedure. The second form causes the 
value returned by the procedure to be printed according to format m. If no 
format is given, it defaults to d. 

linenumber b commands 

Sets a breakpoint at the given line. If a procedure name without a line 
number is given (e.g., proc:), a breakpoint is placed at the first line in the 
procedure even if it was not compiled with the -g option. If no linenumber 
is given, a breakpoint is placed at the current line. If no commands are 
given, execution stops at the breakpoint and control is returned to sdb. 
Otherwise the commands are executed when the breakpoint is encountered. 
Multiple commands are specified by separating them with semicolons. 
Nested associated commands are not permitted; setting breakpoints within 
the associated environments is permitted. 

B Prints a list of the currently active breakpoints. 

linenumber d 

Deletes a breakpoint at the given line. If no linenumber is given, then the 
breakpoints are deleted interactively. Each breakpoint location is printed 
and a line is read from the standard input. If the line begins with a y or d, 
then the breakpoint is deleted. 

D Deletes all breakpoints. 

1 Prints the last executed line. 

linenumber a 

Announces a line number. If linenumber is of the form proc: number, the 
command effectively does a linenumber ih l;c. If linenumber is of the form 
proc:, the command effectively does a proc:h T;c. 
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Miscellaneous commands: 
§resi-of-line 

The rest-of'line represents comments that are ignored by sdb, 

! command 

The command is interpreted by sh. 

new-line 

If the previous command printed a source line, then advance the current 
line by one line and print the new current line. If the previous command 
displayed a memory location, then display the next memory location. If the 
previous command disassembled an instruction, then disassemble the next 
instruction. 

end-of-file character 

Scrolls the next 10 lines of instructions, source, or data depending on which 
was printed last. The end-of-file character is usually control-d 

< filename 

Read commands from filename until the end of file is reached, and then con- 
tinue to accept commands from standard input. Commands are echoed, 
preceded by two asterisks, just before being executed. This command may 
not be nested; < may not appear as a command in a file. 

M Prints the address maps. 

" string " 

Prints the given string. The C escape sequences of the form \character, 
\octaldigits, or Xxhexdigits are recognized, where character is a nonnumeric 
character. The trailing quote may be omitted. 

q Exits the debugger. 

V Prints version stamping information. 

SEE ALSO 

cc(l), signal(2), a. out (4), core(4). 

ed(l), gcore(l), sh(l) in the User's Reference Manml 

The "sdb" chapter in the Programmer's Guide: ANSI C and Prograrnming Support 
Tools. 

NOTES 

The objfile argument is accessed directly for debugging information while the pro- 
cess is created via the PATH variable. 
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NAME 

size - print section sizes in bytes of object files 

SYNOPSIS 

size [ -F ~f -n -o -V -x] files 

DESCRIPTION 

The size command produces segment or section size information in bytes for 
each loaded section in ELF or Cc3FF object files, size prints out the size of the 
text, data, and bss (uninitialized data) segments (or sections) and their total. 

size processes ELF and COFF object files entered on the command line. If an 
archive file is input to the size command, the information for each object file in 
the archive is displayed. 

When calculating segment information, the size command prints out the total 
file size of the non-writable segments, the total file size of the writable segments, 
and the total memory size of the writable segments minus the total file size of the 
writable segments. 

If it cannot calculate segment information, size calculates section information. 
When calculating section information, it prints out the total size of sections that 
are allocatable, non-writable, and not NOBITS, the total size of the sections that 
are allocatable, writable, and not NOBITS, and the total size of the writable sec- 
tions of type NOBITS. (NOBITS sections do not actually take up space in the file.) 

If size cannot calculate either segment or section information, it prints an error 
message and stops processing the file. 

-F Prints out the size of each loadable segment, the permission flags of the 
segment, then the total of the loadable segment sizes. If there is no seg- 
ment data, size prints an error message and stops processing the file. 

-f Prints out the size of each allocatable section, the name of the section, 
and the total of the section sizes. If there is no section data, size prints 
out an error message and stops processing the file. 

-n Prints out non-loadable segment or non-allocatable section sizes. If seg- 
ment data exists, size prints out the memory size of each loadable seg- 
ment or file size of each non-loadable segment, the permission flags, and 
the total size of the segments. If there is no segment data, size prints 
out, for each allocatable and non-allocatable section, the memory size, 
the section name, and the total size of the sections. If there is no seg- 
ment or section data, size prints an error message and stops processing. 

-o Prints numbers in octal, not decimal. 

-V Prints the version information for the size command on the standard 
error output. 

-X Prints numbers in hexadecimal; not decimal. 
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EXAMPLES 

The examples below are typical size output. 
3ize file 2724 + 88 + 0 = 2812 

size -ffile 26 (.text) + 5(.init) + 5(.fini) = 36 

size 'Ffile 2724 (r-x) + 88(rwxy + 0(rwxy = 2812 

SEE ALSO 

as(l),cc(l)v ld(l), a.out(4y, ar(4). 

NOTES 

Since the size of bss sections is not known until link-edit time, the size command 
will not give the true total size of pre-linked objects. 
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NAIME 

strip - strip symbol table, debugging and line number information from an 
object file. 

SYNOPSIS 

strip [-blrVx] file ... 

DESCRIPTiON 

The strip command strips the symbol table, debugging information, and line 
number information from ELF object files; COFF object files can no longer be 
stripped. Once this stripping process has been done, no symbolic debugging 
access will be available for that file; therefore, this command is normally run only 
on production modules that have been debugged and tested. 

If strip is executed on a common archive file [see ar(4)] in addition to process- 
ing the members, strip will remove the archive symbol table. The archive sym- 
bol table must be restored by executing the ar(l) command with the ~s option 
before the archive can be linked by the ld(l) command, strip will produce 
appropriate warning messages when this situation arises. 

The amoimt of information stripped from the ELF object file can be controlled by 
using any of the following options: 

-b Same effect as the default behavior. This option is obsolete and will be 

removed in the next release. 

-1 Strip line number information only; do not strip the symbol table or 

debugging information. 

-r Same effect as the default behavior. This option is obsolete and will be 

removed in the next release. 

-V Print, on standard error, the version number of strip. 

-X Do not strip the symbol table; debugging and line number information 

may be stripped. 

strip is used to reduce the file storage overhead taken by the object file. 

FILES 

TMPDIK/strp* temporary files 

TMPDIR usually /usr/tirp but can be redefined by setting the 

environment variable TMPDIR [see tempnamO in 
tirpnaxn(3S)]. 

SEE ALSO 

ar(l), as(l), cc(l), ld(l), tropnam(3S), a.out(4), ar(4). 

NOTES 

The s)nnbol table section will not be removed if it is contained within a segment, 
or the file is either a relocatable or dynamic shared object. 

The line number and debugging sections will not be removed if they are con- 
tained within a segment, or their associated relocation section is contained within 
a segment. 
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NAME 

tsort - topological sort 

SYNOPSIS 

tsort [file] 

DESCRIPTION 

The tsort command produces on the standard output a totally ordered list of 
items consistent with a partial ordering of items mentioned in the input file. If no 
file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by blanks. Pairs 
of different items indicate ordering. Pairs of identical items indicate presence, but 
not ordering. 

SEE ALSO 

lorder(l). 

DIAGNOSTICS 

Odd data : there is an odd number of fields in the input file. 
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NAME 

unget - undo a previous get of an SCCS file 

SYNOPSIS 

unget [-rSID] [-s] [-n] files 

DESCRIPTION 

unget undoes the effect of a get -e done prior to creating the intended new 
delta. If a directory is named, unget behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files and unreadable files are 
silently ignored. If a name of - is given, the standard input is read with each line 
being taken as the name of an SCCS file to be processed. 

Keyletter arguments apply independently to each named file. 

-rS/D Uniquely identifies which delta is no longer intended. (This 

would have been specified by get as the "new delta"). The 
use of this keyletter is necessary only if two or more outstand- 
ing gets for editing on the same SCCS file were done by the 
same person (login name), A diagnostic results if the specified 
SID is ambiguous, or if it is necessary and omitted on the com- 
mand line, 

-s Suppresses the printout, on the standard output, of the 

intended delta's SID. 

-n Causes the retention of the gotten file, which would normally 

be removed from the current directory. 

unget must be performed by the same user whp performed the original get -e. 

FILES 

p-file [?ee delta(l)] 

q-file [see delta(l)] 

z-file [§^e delta(l)] 

SEE ALSO 

delta(l), get(l), help(l), saet(l). 

DIAGNOSTICS 

Use help(l) for e>cplaiiatiQns. 



10/89 



val(1) 



val(1) 



NAME 

val - validate an SCCS file 

SYNOPSIS 

val - 

val [-s] [-rS/D] [^smame] [-ytype] files 
DESCRIPTION 

val determines if the specified file is an SCCS file meeting the characteristics 
specified by the optional argument list. Arguments to val may appear in any 
order. The arguments consist of keyletter arguments, which begin with a and 
named files. 

val has a special argument, which causes reading of the standard input until 
an end-of-file condition is detected. Each line read is independently processed as 
if it were a command line argument list. 

val generates diagnostic messages on the standard output for each command line 
and file processed, and also returns a single 8-bit code on exit as described below. 

The keyletter arguments are defined as follows. The effects of any keyletter argu- 
ment apply independently to each named file on the command line. 

-s The presence of this argument silences the diagnostic message nor- 

mally generated on the standard output for any error that is 
detected while processing each named file on a given command line. 

-rS/D The argument value SID (SCCS identification string) is an SCCS delta 

number. A check is made to determine if the SID is ambiguous (e. 
g., -rl is ambiguous because it physically does not exist but implies 
1.1, 1.2, etc., which may exist) or invalid (e. g., rl.O or r 1.1.0 are 
invalid because neither can exist as a valid delta number). If the SID 
is valid and not ambiguous, a check is made to determine if it actu- 
ally exists. 

-^laname The argument value name is compared with the SCCS %M% keyword 
in file. 

-ytype The argument value type is compared with the SCCS %Y% keyword in 
file. 

The 8-bit code returned by val is a disjunction of the possible errors; it can be 
interpreted as a bit string where (moving from left to right) set bits are inter- 
preted as follows: 

bit 0 = missing file argument 

bit 1 = unknown or duplicate keyletter argument 

bit 2 = corrupted SCCS file 

bit 3 = cannot open file or file not SCCS 

bit 4 = SID is invalid or ambiguous 

bit 5 = SID does not exist 

bit 6 = %Y%, -y mismatch 

bit 7 = %M%, -m mismatch 
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val can process two or more files on a given command line and in turn can pro- 
cess mtiHlple command lines (when reading the standard input). In these cases 
an a^^ate code is r^urned: a logical OR of the codes generated for each com- 
mand line and file processed. 

$ii ALSO 

adiBifidX deltad), getd), belpCl, prs(l). 
PIAGNOSTK^ 

Use help(l) for explanations. 

NOTES 

val can process up to 50 files on a single command line. 
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NAME 

vc - version control 
SYNOPSIS 

vc [-a] [-t] l-cchar} [-s] [keyword=value ... keyioord=value} 
DESCRIPTION 

This command is obsolete and will be removed in the next release. 

The vc command copies lines from the standard input to the standard output 
under control of its arguments and of "control statements" encountered in the 
standard input. In the process of performing the copy operation, user-declared 
keywords may be replaced by their string value when they appear in plain text 
and /or control statements. 

The copying of lines from the standard input to the standard output is condi- 
tional, based on tests (in control statements) of keyword values specified in con- 
trol statements or as vc command argimients. 

A control statement is a single line beginning with a control character, except as 
modified by the -t keyletter (see below). The default control character is colon 
(:), except as modified by the ~c keyletter (see below). Input lines beginning 
with a backslash (\) followed by a control character are not control lines and are 
copied to the standard output with the backslash removed. Lines beginning with 
a backslash followed by a non-control character are copied in their entirety. 

A keyword is composed of 9 or less alphanumerics; the first must be alphabetic. 
A value is any ASQI string that can be created with ed; a nimieric value is an 
unsigned string of digits. Keyword values may not contain blanks or tabs. 

Replacement of ke)words by values is done whenever a keyword surrotmded by 
control characters is encoimtered on a version control statement. The -a keyletter 
(see below) forces replacement of ke)rwords in all lines of text. An uninterpreted 
control character may be included in a value by preceding it with \. If a literal \ 
is desired, then it too must be preceded by \. 

The following options are valid: 

-a Forces replacement of keywords surrounded by control characters 

with their assigned value in all text lines and not just in vc state- 
ments. 

-t All characters from the beginning of a line up to and including the 

first tab character are ignored for the purpose of detecting a control 
statement. If a control statement is found, all characters up to and 
including the tab are discarded. 

-cchar Specifies a control character to be used in place of the " : " default. 

-s Silences warning messages (not error) that are normally printed on 

the diagnostic output. 

vc recognizes the following version control statements: 

: del keyioordl, keyxoord] 

Declare ke5words. All keywords must be declared. 
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: asg keyword^value 

Assign values to keywords. An asg statement overrides the assignment 
for the corresponding keyword on the vc command line and all previous 
asg statements for that kejword. Keywords that are declared but are not 
assigned values have null values. 

: if condition 
:end 

Skip lines of the standard input. If the condition is true, all lines between 
the if statement and the matching end statement are copied to the stan- 
dard output. If the condition is false, all intervening lines are discarded, 
including control statements. Note that intervening if statements and 
matching end statements are recognized solely for the purpose of main- 
taining the proper if-end matching. 

The syntax of a condition is: 

<cond> ::= [ "not" ] <or> 

<or> ::= <and> I <and> " I " <or> 

<smd> ::= <ex}fr> I <£xp> "h" <and> 

<exp> ::= <or> I <value> <op> <value> 

<op> ::= I "!=" I I 

<value> ::= <arbitrary ASCII stnng> I <numeric string> 

The available operators and their meanings are: 

= equal 

!= not equal 

& and 

I or 

> greater than 

< less than 

( ) used for logical groupings 

not may only occur immediately after the if, and when 
present, inverts the value of the entire condition 

The > and < operate only on unsigned integer values (e.g., : 012 > 12 is 
false). All other operators take strings as arguments (e.g., : 012 != 12 is 
true). 

The precedence of the operators (from highest to lowest) is: 

= != > < all of equal precedence 
& 

I 

Parentheses may be used to alter the order of precedence. 

Values must be separated from operators or parentheses by at least one 
blank or tab. 
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: itext 

Replace ke5rwords on lines that are copied to the standard output. The 
two leading control characters are removed, and keywords surrounded by 
control characters in text are replaced by their value before the line is 
copied to the output file. This action is independent of the -a keyletter. 

:on 

:off Turn on or off keyword replacement on all lines. 

: ctl char 

Qiange the control character to char. 

:xnsg message 

Print message on the diagnostic output. 

: err message 

Print message followed by: 

ERROR: err statement on line ... (915) 

on the diagnostic output, vc halts execution, and returns an exit code of 1. 

SEE ALSO 

help(l). 

ed(l) in the User's Reference Manual 
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NAME 

what - print identification strings 

SYNOPSIS 

what [sj files 

DESCRIPTION 

what searches the given files for all occurrences of the pattern that the get com- 
mand substitutes for %Z% (this is @ (t) at this printing) and prints out what fol- 
lows imtil the first >, new-line, \, or null character. For example, if the C pro- 
gram in file f . c contains 

#ident " 8 {%) identification information " 

and f .c is compiled to yield f .o and a. out, then the command 

what £ .c £ .0 a. out 

prints 

f.c: 

identification information 

f.c: 

identificMion infomnation 

a . out : 

identification information 

what is intended to be used in conjunction with the get command, which 
automatically inserts identifying informaticnv but it can also be used wte^e the 
information is inserted manually. Only one option exists: 

-s Quit after finding the first occurrence of pattern in. each fila 

SEE ALSO 

get(l), Imlpd)^ incs<l). 

DIAGNOSTK^S 

Exit status is Ot if any matdies are found, otherwise 1. See help(l) for explana- 
tions. 
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NAME 

yacc - yet another compiler-compiler 

SYNOPSIS 

yacc [-vVdlt] [-Q[y|n]]/ik 

DESCRIPTION 

The yacc command converts a context-free grammar into a set of tables for a 
simple automaton that executes an LALR(l) parsing algorithm. The grammar may 
be ambiguous; specified precedence rules are used to break ambiguities. 

The output file, y.tab.c, must be compiled by the C compiler to produce a pro- 
gram yyparse. This program must be loaded with the lexical analyzer program, 
yylex;, as well as main and yyerror, an error handling routine. These routines 
must be supplied by the user; the lex(l) command is useful for creating lexical 
analyzers usable by yacc. 

-V Prepares the file y. output, which contains a description of the parsing 

tables and a report on conflicts generated by ambiguities in the gram- 
mar. 

-d Generates the file y.tab.h with the #define statements that associate 

the yacc-assigned "token codes" with the user-declared "token names." 
This association allows source files other than y.tab.c to access the 
token codes. 

-1 Specifies that the code produced in y.tab.c will not contain any #line 

constructs. This option should only be used after the grammar and the 
associated actions are fully debugged. 

-Q[y|n] The option puts the version stamping information in y.tab.c. 

This allows you to know what version of yacc built the file. The -Qn 
option (the default) writes no version information. 

-t Compiles runtime debugging code by default. Runtime debugging 

code is always generated in y.tab.c under conditional compilation 
control. By default, this code is not included when y.tab.c is com- 
piled. Whether or not the -t option is used, the runtime debugging 
code is under the control of YYDEBUG, a preprocessor symbol. If YYDE- 
BU6 has a non-zero value, then the debugging code is included. If its 
value is zero, then the code will not be included. The size and execu- 
tion time of a program produced without the runtime debugging code 
will be smaller and slightly faster. 

-V Prints on the standard error output the version information for yacc. 

FILES 

y . output 
y.tab.c 

y . tab . h defines for token names 

yacc.tnp, 

yacc. debug, yacc. acts temporary files 
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LIBDIR/yaffcpar parser prototype for C programs 

LIBDIR usually /usxr/ccs/lib 

SEE ALSO 

lexd). 

The "yacc" chapter in the Programmer's Guide: ANSI C and Programming Support 
Tools. 

DIAQNOSTtCS 

The nuraber of reduce-reduce and shift-reduce conflicts is reported on the stan- 
dard error output; a more detailed report is found in the y. output file. Simi- 
larly, if some rules are not reachable from the start symbol, this instance is also 
reported. 

Because file names are fixed,, at most one yac^q process can be active in a giyen 
directory at a givei> time. 
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NAME 

intro - introduction to system calls and error numbers 

SYNOPSIS 

♦include <ermo.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls have one or 
more error returns. An error condition is indicated by an otherwise impossible 
returned value. This is almost always -1 or the NULL pointer; the individual 
descriptions specify the details. An error number is also made available in the 
external variable errno, errno is not cleared on successful calls, so it should be 
tested only after an error has been indicated. 

Each system call description attempts to list all possible error numbers. The fol- 
lowing is a complete list of the error numbers and their names as defined in 
<errno.h>. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file in some way for- 
bidden except to its owner or super-user. It is also returned for attempts 
by ordinary users to do things allowed only to the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should exist 
but doesn't, or when one of the directories in a path name does not exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified by ptd in kill(2) 
or ptrace(2). 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user has 
elected to catch, occurred during a system call. If execution is resumed 
after processing the signal, it will appear as if the interrupted system call 
returned this error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in some cases 
occur on a call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist, or beyond 
the limits of the device. It may also occur when, for example, a tape drive 
is not on-line or no disk pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a member of the 
exec(2) family. 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the appropriate 
permissions, does not start with a valid magic number [see a. out (4)]. 
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9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read(2) [respectively, 
write(2)] request is made to a file which is open only for writing (respec- 
tively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or imwaited-for 
child processes. 

11 EAGAIN No more processes 

A fork failed because the system's process table is full or the user is not 
allowed to create any more processes. Or a system call failed because of 
insufficient memory or swap space. 

12 ENOMEM Not enough space 

During an exec(2), brk(2), or sbrk(2), a program asks for more space than 
the system is able to supply. This may not be a temporary condition; the 
maximum space size is a system parameter. The error may also occur if 
the arrangement of text, data, and stack segments requires too many seg- 
mentation registers, or if there is not enough swap space during a fork(2). 
If this error occurs on a resource associated with Remote File Sharing 
(RF5), it indicates a memory depletion wich may be temporary, dependent 
on system activity at the time the call was invoked. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the protection 
system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use an argu- 
ment of a system call. 

15 ENOTBLK Block device required 

A non-block file was mentioned where a block device was required, e.g., 
in mount (2). 

16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already mounted or an 
attempt was made to dismount a device on which there is an active file 
(open file, current directory, mounted-on file, active text segment). It will 
also occur if an attempt is made to enable accounting when it is already 
enabled. The device or resource is currently unavailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., link(2). 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a device; 
e.g., read a write-only device. 
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20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for example 
in a path prefix or as an argument to chdir(2). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted device; men- 
tioning an imdefined signal in signal(2) or kill(2); reading or writing a 
file for which lseek(2) has generated a negative pointer). Also set by the 
math functions described in the (3M) entries of this manual. 

23 ENHLE File table overflow 

The system file table is full, and temporarily no more opens can be 
accepted. 

24 EMFILE Too many open files 

No process may have more than NOFILES (default 20) descriptors open at 
a time. 

25 ENOTTY Not a character device (or) Not a typewriter 

An attempt was made to ioctl(2) a file that is not a special character dev- 
ice. 

26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure program that is 
currently open for writing. Also an attempt to open for vsrriting or to 
remove a pure-procedure program that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size or ULIMIT [see 
ulimit(2)]. 

28 ENOSPC No space left on device 

During a write(2) to an ordinary file, there is no frm space left on the 
device. In f cntl(2), the setting or removing of record locks on a file can- 
not be accomplished because there are no more record entries left on the 
system. 

29 ESPIPE Illegal seek 

An lseek(2) was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device mounted 
read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum number of links (10(X)) to a 
file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to read the data. This 
condition normally generates a signal; the error is returned if the signal is 
ignored. 
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EDOM Math argument 

The argument of a function in the math package (3M) is out of the domain 
of the function. 

ERANGE Result too large 

The value of a function in the math package (3M) is not representable 
within machine precision. 

ENOMSG No message of desired type 

An attempt was made to receive a message of a type that does not exist 
on the specified message queue [see xnsgop(2)]. 

EIDRM Identifier removed 

This error is returned to processes that resume execution due to the remo- 
val of an identifier from the file system's name space [see insgctl(2), 
semctl(2), and shmctl(2)]. 

37-44 Reserved numbers 

45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. This error pertains to file 
and record locking. 

46 ENOLCK No lock 

In fcntl(2) the setting or removing of record locks on a file cannot be 
accomplished because there are no more record entries left on the system. 

60 ENOSTR Not a stream 

A put:msg(2) or getinsg(2) system call was attempted on a file descriptor 
that is not a STREAMS device. 

62 ETME Stream ioctl timeout 

The timer set for a STREAMS ioctl(2) call has expired. The cause of this 
error is device specific and could indicate either a hardware or software 
failure, or perhaps a timeout value that is too short for the specific opera- 
tion. The status of the ioctl(2) operation is indeterminate. 

63 ENOSR No stream resources 

Insufficient STREAMS memory resources are available to perform a 
STREAMS related system call. This is a non-recoverable error and requires 
the system to be reconfigured with additional STREAMS memory 
resources. 

64 ENONET Machine is not on the network 

This error is Remote File Sharing (RFS) specific. It occurs when users try 
to advertise, unadvertise, mount, or immount remote resources while the 
machine has not done the proper startup to connect to the network. 

65 ENOPKG No package 

This error occurs when users attempt to use a system call from a package 
which has not been installed. 
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EREMOTE Resource is remote 

This error is RFS specific. It occurs when users try to advertise a resource 
which is not on the local machine, or try to mount /unmount a device (or 
pathname) that is on a remote machine. 

ENOLINK Virtual circuit is gone 

This error is RFS specific. It occurs when the link (virtual circuit) connect- 
ing to a remote machine is gone. 

EADV Advertise error 

This error is RFS specific. It occurs when users try to advertise a resource 
which has been advertised already, or try to stop the RFS while there are 
resources still advertised, or try to force unmount a resource when it is 
still advertised. 

ESRMNT Srmount error 

This error is RFS specific. It occurs when users try to stop RFS while there 
are resources still mounted by remote machines. 

ECOMM Communication error 

This error is RFS specific. It occurs when trying to send messages to 
remote machines but no virtual circuit can be found. 

EPROTO Protocol error 

Some protocol error occurred. This error is device specific, but is gen- 
erally not related to a hardware failure. 

EMULTIHOP Multihop attempted 

This error is RFS specific. It occurs when users try to access remote 
resources which are not directly accessible. 

EBADMSG Bad message 

During a read(2), getinsg(2), or ioctl(2) I^RECVFD system call to a 
STREAMS device, something has come to the head of the queue that can't 
be processed. That something depends on the system call: 

read(2) - control information or a passed file descriptor. 

getinsg(2) - passed file descriptor. 

ioctl(2) - control or data information. 

ELIBACC Cannot access a needed shared library 

Trying to exec(2) an a . out that requires a shared library (to be linked in) 
and the shared library doesn't exist or the user doesn't have permission to 
use it. 

ELIBBAD Accessing a corrupted shared library 

Trying to exec(2) an a . out that requires a shared library (to be linked in) 
and exec(2) could not load the shared library. The shared library is prob- 
ably corrupted. 

ELIBSCN .lib section in a. out corrupted 

Trying to exec(2) an a. out that requires a shared library (to be linked in) 
and there was erroneous data in the .lib section of the a. out. The .lib sec- 
tion tells exec(2) what shared libraries are needed. The a. out is probably 
corrupted. 
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86 ELIBMAX Attempting to link in more shared libraries than system limit 

Trying to exec(2) an a. out that requires more shared libraries (to be 
linked in) than is allowed on the current configuration of the system. See 
the System Administrators Guide, 

87 ELIBEXEC Cannot exec a shared library directly 

Trying to exec(2) a shared library directly. This is not allowed. 

DEFINITIONS 

Process ID Each active process in the system is imiquely identified by a positive 
integer called a process ID. The range of this ID is from 1 to 30,000. 

Parent Pi-otes^ ID A ne^w process is created by a currently active process |see 
£drk(2)l. The parent process ID of a process is the process ID of its creator. 

Process Group ID Each active process is a member of a process group that is 
identified by a positive integer called the process group ID. This ID is the process 
ID of the group leader. This grouping permits the signaling of related processes 
[see kill(2)]. 

Tty Group ID Each active process can be a member of a terminal group that is 
identified by a positive integer called the tty group ID. This grouping is used to 
terminate a group of related processes upon termination of one of the processes 
in the group [see ^it(2) and signal(2)]. 

Real User ID and Real Group ID Each user allowed on the system is identified 
by a positive integer (0 to 65535) called a real user ID. 

Each user is also a member of a group. The group is identified by a positive 
integer called the real group ID. 

An active process has a real user ID and real group ID that are set to the relil user 
ID and real group ID, respectively, of the user responsible for the creatibh of the 
process. 

Effective User ID and Effective Croup ID An active process has an effective user 
ID and an effective group ID that are used to determine file access permissions 
(see b^low). The effective user ID and effective group ID are equal to the 
process's real user ID and real group ID respectively, unless the process or one of 
its ancestors evolved from a file that had the set-user-ID bit or set-group ID bit set 
[see exeG(2)]. 

SupeT'^tisei' A ptt>cess is recognised ai§ ^ ^uper-user process and is granted special 
privileges, such as immunity from file permissions, if its effective user ID is 0. 

Special Precised The processes with a process ID of 0 and a process ID of 1 are 
special processes and are referred to as procO and prod . 
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procO is the scheduler, prod is the initialization process (init). prod is the ances- 
tor of every other process in the system and is used to control the process struc- 
ture. 

File Descriptor A file descriptor is a small integer used to do I/O on a file. The 
value of a file descriptor is from 0 to (NOFILES - 1). A process may have no 
more than NOFILES file descriptors open simultaneously. A file descriptor is 
returned by system calls such as open(2), or pipe(2). The file descriptor is used 
as an argument by calls such as read(2), write(2), ioctl(2), and close(2). 

File Name Names consisting of 1 to 14 characters may be used to name an ordi- 
nary file, special file or directory. 

These characters may be selected from the set of all character values excluding 
(null) and the ASQI code for / (slash). 

Note that it is generally imwise to use *, ?, or ] as part of file names because 
of the special meaning attached to these characters by the shell [see sh(l)]. 
Although permitted, the use of unprintable characters in file names should be 
avoided. 

Path Name and Path Prefix A path name is a null-terminated character string 
starting with an optional slash (/), followed by zero or more directory names 
separated by slashes, optionally followed by a file name. 

If a path name begins with a slash, the path search begins at the root directory. 
Otherwise, the search begins from the current working directory. 

A slash by itself names the root directory. 

Unless specifically stated otherwise, the null path name is treated as if it named a 
non-existent file. 

Directory Directory entries are called links. By convention, a directory contains 
at least two links, . and . ,, referred to as dot and dot-dot respectively. Dot 
refers to the directory itself and dot-dot refers to its parent directory. 

Root Directoiy and Current Working Directory Each process has associated with 
it a concept of a root directory and a current working directory for the purpose 
of resolving path name searches. The root directory of a process need not be the 
root directory of the root file system. 

File Access Permissions Read, write, and execute/search permissions on a file are 
granted to a process if one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the owner of 
the file and the appropriate access bit of the "owner" portion (0700) of the 
file mod? is set. 
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The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process matches the 
group of the file and the appropriate access bit of the ''group" portion 
(0070) of the file mode is set. 

The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process does not match 
the group ID of the file, and the appropriate access bit of the ''other" por- 
tion (0007) of the file mode is set. 

CXherwise, the corresponding permissions are denied. 



Message Queue Identifier A message queue identifier (msqid) is a unique posi- 
tive integer created by a msgget(2) system call. Each msqid has a message queue 
and a data structure associated with it. The data structure is referred to as 
msqid_ds and contains the following members: 

struct ipc_j>enn insg_perm; 
struct msg *msg_first; 
struct insg *insg_last; 
ushort xnsgjDbytes; 
ushort msgjqnum; 
ushort msgjq^ytes; 
ushort msg^lspid; 
ushort msg^lrpid; 
time__t msg^stime; 
timejt insg_rtiine; 
tiine_t msgjctime; 

xnsg_perm is an ipc^perm structure that specifies the message operation permis- 
sion (see below). This structure includes the following members: 

ushort cuid; /* creator user id */ 

ushort cgid; /* creator group id */ 

ushort uid; /* user id */ 

ushort gid; /* group id */ 

ushort mode; /* r/w permission */ 

ushort seq; /* slot usage sequence # */ 

keyjt key; /* key */ 

msg *msg__first 

is a pointer to the first message on the queue. 

msg *msg_last 

is a pointer to the last message on the queue. 

msgjcbytes 

is the current number of bytes on the queue. 

msgjqpium 

is the number of messages currently on the queue. 
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insg_<#>ytes 

is the maximum number of bytes allowed on the queue. 
insg__lspid 

is the process id of the last process that performed a msgsnd operation. 
insg_lrpid 

is the process id of the last process that performed a rosgrcv operation. 

xnsg_stiine 

is the time of the last xnsgsnd operation. 

msg_rtime 

is the time of the last msgrcv operation. 

xnsgjctixne 

is the time of the last insgctl(2) operation that changed a member of the 
above structure. 

Message Operation Permissions In the insgop(2) and insgct.l(2) system call 
descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type of permission needed, interpreted as follows: 



00400 Read by user 

00200 Write by user 

00040 Read by group 

00020 Write by group 

00004 Read by others 

00002 Write by others 



Read and write permissions on a msqid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches insg_j>erm.cuid or 
insg_j>erm.uid in the data structure associated with msqid and the 
appropriate bit of the "user" portion (0600) of xnsgjperm.mode is set. 

The effective group ID of the process matches msg_perm.cgid or 
msgjperm.gid and the appropriate bit of the "group" portion (060) of 
xnsg^perm.inode is set. 

The appropriate bit of the "other" portion (006) of insg_perm.inode is set. 
Otherwise, the corresponding permissions are denied. 

Semaphore Identifier A semaphore identifier (semid) is a unique positive integer 
created by a semget(2) system call. Each semid has a set of semaphores and a 
data structure associated with it. The data structure is referred to as semidjds 
and contains the following members: 

struct ipcjperm senrpem;/* operation permission struct ♦/ 

struct sem ♦sem_base/ /* ptr to first semaphore in set */ 

ushort sem_jisems; /* nuirber of sems in set */ 

timejt sem__otime; /* last operation time */ 
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tiififej: s^jctime; /* last change tiine */ 

/* Times measured in sees since */ 
/* 00:00:00 GMI?, Jan. 1, 1970 */ 

semjpem is an ipc j>erm structiire that specifies the semaphore operation permis- 
sion below), litis structure includes the following members: 

tishort uid; /* user id */ 

ushort gid; /* groi:^ id */ 

ushort cuid; /* creator user id ♦/ 

\2short cgid; /* creator group id */ 

ti^tiort mode; /* r/a permission */ 

ushort seq; slot usage sequence nurti:>er 

keyjt key; /* key */ 

si^_nsems 

is equal to the number of semaphores in the set. Each semaphore in the 
set is referenced by a positive int^er referred to as a ^mjtuan, semjium 
values run sequentially from 0 to the value of sem_nsems minus 1. 

s^njotime 

is the time of the last seitiDp(2) operation. 

i^iafintgtiM 

is the time Of the last semctl(2) operation that changed a member of the 
above structure. 

A semaphore is a data structure called $em that contains the following members: 

ushort semval; /♦ semaphore value */ 

short sempid; /* pid of last operation */ 

u^ort seronoit; /♦ # awaiting semval > cval */ 

ushort defRzcnt; /* t awaiting semval * 0 */ 

is a non-negative integer which is the actual value of the semphore. 
s^i^oDpid 

is equal to the process ID of the last process that performed a semaphore 
operation on this semaphore. 

S0mncnt 

is a count of the niamber of processes that are currently suspended await- 
ing this semaphore's semval to become greater tham its tiurrent vulxie. 

s^^ent 

is a co\mt of the number of processes that are currently suspended await- 
ing this semaphore's semval to become zero. 
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Semaphore Operation Permissions In the senK>p(2) and semctl(2) system call 
descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type? of permission needed interpreted as follows: 



00400 Read by user 

00200 Alter by user 

00040 Read by group 

00020 Alter by group 

00004 Read by others 

00002 Alter by others 



Read and alter permissions on a semid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches semjperm.cuid or 
semjp€^rm.uid in the data structure associated with semid and the 
appropriate bit of the "user" portion (0600) of seiiij>em.node is set. 

The effective group ID of the process matches senv_pena.cgid or 
sexnj)erm.gid and the appropriate bit of the "group" portion (060) of 
semjjerm.mode is set. 

The appropriate bit of the "other" portion (006) of sem_j>erm.iiiode is set. 
Otherwise, the corresponding permissions are denied. 



Shared Memory Identifier A shared memory identifier (shmid) is a unique posi- 
tive integer created by a shjnget(2) system call. Each shmid has a segment of 
memory (referred to as a shared memory segment) and a data structure associ- 
ated with it. (Note that these shared memory segments must be explicitly 
removed by the user after the last reference to them is removed.) The data struc- 
ture is referred to as shmidjis and contains the following members; 

struct ipc^perm shmjperm;/* operation permission struct */ 



/* size of segront ♦/ 
/*ptr to region structure */ 
/* for swap cocnpatibility */ 
/* pid of last qperatioi^ */ 
/* creator pid ♦/ 
/* nurcber of qurriii^ s^tacl^e^s */ 
/* used only for slm»fo */ 
/* last attach time */ 
/* last det:ach time */ 
/♦ last change time ♦/ 
/* Times measured in sees since */ 
/* 00:00:00 OC, Jan. 1, 1970 */ 

stoperm is m ipcjp^rm structure that specifies th^ shared memoiy operation 
permissiou (s€^ below). Th^ Bkm0m^ indudesf the following members: 



int shm_segsz; 

struct region *shm_reg; 

char pad[4]; 

ushort shm_lpid; 

ushort shmjqpid; 

ushort shmjnattch; 

ushort shmjcnattch; 

timejt shmjatime; 

tiroejb shmjcfeime; 

tima t aim ctime; 
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ushort cuid; /* creator user id */ 

ushort cgid; /* creator group id */ 

ushort uid; /* user id */ 

ushort gid; /* group id */ 

ushort mode; /* r/w permission */ 

ushort seq; /* slot usage sequence # */" 

keyjt key; /* key */ 

shmjsegsz specifies the size of the shared memory segment in bytes. 

shmjcpid is the process id of the process that created the shared memory 
identifier. 

shm_lpid is the process id of the last process that performed a shinDp(2) 
operation. 

shmjiattch is the nimiber of processes that currently have this segment 
attached. 

shmjatiroe is the time of the last shmat operation, 
shmjitiine is the time of the last shmdt operation. 

shmjctiine is the time of the last shinctl(2) operation that changed one of the 
members of the above structure. 



Shared Memory Operation Permissions In the shitK>p(2) and shitvctl(2) system 
call descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type of permission needed interpreted as follows: 

00400 Read by user 

00200 Write by user 

00040 Read by group 

00020 Write by group 

00004 Read by others 

00002 Write by others 

Read and write permissions on a shmid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm_perm.cuid or 
shm_perm.uid in the data structure associated with shmid and the 
appropriate bit of the "user" portion (0600) of shmjperm.mode is set. 

The effective group ID of the process matches shmjperm.cgid or 
shinj>erm.gid and the appropriate bit of the "group" portion (060) of 
shm_perm.niDde is set. 

The appropriate bit of the "other" portion (06) of shmjperm.mode is set. 
Otherwise, the corresponding permissions are denied. 
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STREAMS A set of kernel mechanisms that support the development of network 
services and data communication drivers. It defines interface standards for char- 
acter input/output within the kernel and between the kernel and user level 
processes. The STREAMS mechanism is composed of utility routines, kernel facili- 
ties and a set of data structures. 

Stream A stream is a full-duplex data path within the kernel between a user pro- 
cess and driver routines. The primary components are a stream head, a driver and 
zero or more modules between the stream head and driver. A stream is analogous to 
a Shell pipeline except that data flow and processing are bidirectional. 

Stream Head In a stream, the stream head is the end of the stream that provides the 
interface between the stream and a user process. The principle functions of the 
stream head are processing STREAMS-related system calls, and passing data and 
information between a user process and the stream. 

Driver In a stream, the driver provides the interface between peripheral hardware 
and the stream. A driver can also be a pseudo-<inW, such as a multiplexor or log 
driver [see log(7)], which is not associated with a hardware device. 

Module A module is an entity containing processing routines for input and out- 
put data. It always exists in the middle of a stream, between the stream's head 
and a driver. A module is the STREAMS counterpart to the commands in a shell 
pipeline except that a module contains a pair of functions which allow indepen- 
dent bidirectional {downstream and upstream) data flow and processing. 

Downstream In a stream, the direction from stream head to driver. 

Upstream In a stream, the direction from driver to stream head. 

Message In a stream, one or more blocks of data or information, with associated 
STREAMS control structures. Messages can be of several defined types, which 
identify the message contents. Messages are the only means of transferring data 
and communicating within a stream. 

Message Queue In a stream, a linked list of messages awaiting processing by a 
module or driver. 

Read Queue In a stream, the message queue in a module or driver containing mes- 
sages moving upstream. 

Write Queue In a stream, the message queue in a module or driver containing mes- 
sages moving downstream. 
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Multiplexor A multiplexor is a driver that allows streams associated with several 
user processes to be connected to a single driver, or several drivers to be connected 
to a single user process. STREAMS does not provide a general multiplexing driver, 
but does provide the facilities for constructing them, and for connecting miulti- 
pl6xed configurations of streams, 

SEE ALSO 

jLntroO). 
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access - determine accessibility of a file 



SYNOPSIS 

int access (path, axnode) 
c^r ♦path; 
int 



OESCRIPTiON 

path points to a path name naming a file, access checks the named file for acces- 
sibility according to the bit pattern contained in amode, using the real user ID in 
place of the effective user ID and the real group ID in place of the effective group 
ID. The bit pattern contained in amode is constructed as follows: 

04 lead 

02 write 

01 execute (search) 

00 check existence of file 

Access to the file is denied if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] Read, write, or execute (search) permission is 

requested for a null path name. 
[HSrOENT] The named file does not exist. 

[EACCE5] Search permission is denied on a component of the 

path prefix. 

[EROFS] Write access is requested for a file on a read-only 

file system. 

lETXTBSY] Write access is requested for a pure procedure 

(shared text) file that is being executed. 
[EACCES] Permission bits of the file mode do not permit 

the requested access. 
[EFAULT] path points outside the allocated address 

space for the process. 
[EINTR] A signal was caught during the access 

system call. 

[ENOUNK] path points to a remote machine and the link 

to that machine is no longer active. 
lEMULUHOP] Components of path require hopping to multiple 

remote machines. 



Wim owner of a file has permission checked with respect to the "owner" read, 
write, and execute mode bits. Members of the file's group other than the owner 
have permissions checked with respect to the "group" mode bits, and all others 
have p^missicms checked with respect to the 'icHher" mode bits. 
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access (2) access (2) 
DIAGNOSTICS 

If the requested access is permitted, a value of 0 is returned. Otherwise, a value 
of -1 is returned and ermo is set to indicate the error. 
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NAME 

acct - enable or disable process accounting 

SYNOPSIS 

int acct (path) 
char *path; 

DESCRIPTION 

acct is used to enable or disable the system process accounting routine. If the 
routine is enabled, an accounting record will be written on an accounting file for 
each process that terminates. Termination can be caused by one of two things: an 
exit call or a signal [see exit(2) and signal(2)]. The effective user ID of the cal- 
ling process must be superuser to use this call. 

path points to a pathname naming the accounting file. The accounting file format 
is given in acct(4). 

The accounting routine is enabled if path is non-zero and no errors occur during 
the system call. It is disabled if path is zero and no errors occur during the sys- 
tem call. 



acct will fail if one or more of the following are true: 



[EPERM] 


The effective user of the calling process is not superuser. 


[EBUSY] 


An attempt is being made to enable accounting when it is 




already enabled. 


[ENOTDIR] 


A component of the path prefix is not a directory. 


[ENOENT] 


One or more components of the accounting file pathname do not 




exist. 


[EACCES] 


The file named by path is not an ordinary file. 


[EROFS] 


The named file resides on a read-only file system. 


[EFAULT] 


path points to an illegal address. 



SEE ALSO 

exit(2), signal(2), acct(4). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

alarm - set a process alarm clock 

SYNAPSIS 

iinsigned alarm (sec) 
unsigned sec; 

DESCRIPTION 

alarm instructs the alarm clock of the calling process to send the signal SIGALRM 
to the calling process after the number of real time seconds specifi^ by sec have 
elapsed [see signal(2)I. 

Alarm requests are not stacked; successive calls reset the alarm clock of the cal- 
ling process. 

If sec is any previously made alarm request is canceled. 
SEE ALSO 

pause(2), signaK?)/ sigpause(2X sigset(2), 
PIAGNOSTIQS 

alarm returns the amount of time previously remaining in the alarm clock of the 
calling process. 
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NAME 



brk, sbrk - change data segment space allocation 

SYNOPSIS 

int brk (endds) 
char * endds; 
char *sbrk (incr) 
int incr; 

DESCRIPTION 

brk and sbrk are used to change dynamically the amount of space allocated for 
the calling process's data segment [see exec(2)]. The change is made by resetting 
the process's break value and allocating the appropriate amount of space. The 
break value is the address of the first location beyond the end of the data seg- 
ment. The amount of allocated space increases as the break value increases. 
Newly allocated space is set to zero. If, however, the same memory space is real- 
located to the same process its contents are undefined. 

brk sets the break value to endds and changes the allocated space accordingly. 

sbrk adds incr bytes to the break value and changes the allocated space accord- 
ingly, incr can be negative, in which case the amount of allocated space is 
decreased. 

brk and sbrk will fail without making any change in the allocated space if one or 
more of the following are true: 



SEE ALSO 

exec(2), shinop(2), uliinit(2), end(3C). 

DIAGNOSTICS 

Upon successful completion, brk returns a value of 0 and sbrk returns the old 
break value. Otherwise, a value of -1 is returned and ermo is set to indicate the 
error. 



[ENOMEM] 



Such a change would result in more space being allocated 
than is allowed by the system-imposed maximum process 
size [see uliinit(2)]. 



[EAGAIN] 



Total amount of system memory available for a read during 
physical lO is temporarily insufficient [see shroop(2)]. This 
may occur even though the space requested was less than 
the system-imposed maximum process size [see ulimit(2)]. 
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NAME 

chdir - change working directory 

SYNOPSIS 

int chdir (path) 
char *path; 

DESCRIPTION 

path points to the path name of a directory, chdir causes the named directory to 
become the current working directory, the starting point for path searches for 
path names not beginning with /. 

chdir will fail and the current working directory will be unchanged if one or 
more of the following are true: 

[ENOTDIR] A component of the path name is not a directory. 
[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for any component of the path 

name. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the chdir system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chroot(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

chmod - change mode of file 

SYNOPSIS 

int chinod (path, mode) 
char *path; 
int node; 

DESCRIPTION 

path points to a path name naming a file, chitod sets the access permission por- 
tion of the named file's mode according to the bit pattern contained in mode. 

Access permission bits are interpreted as follows: 

04000 Set user ID on execution. 

020#0 Set group ID on execution if # is 7, 5, 3, or 1 

Enable mandatory file/record locking if # is 6, A, 2, or 0 

01000 Save text image after execution. 

00400 Read by owner. 

00200 Write by owner. 

00100 Execute (search if a directory) by owner. 

00070 Read, write, execute (search) by group. 

00007 Read, write, execute (search) by others. 

The effective user ID of the process must match the owner of the file or be super- 
user to change the mode of a file. 

If the effective user ID of the process is not super-user and the file is not a direc- 
tory, mode bit 01000 (save text image on execution) is cleared. 

If the effective user ID of the process is not super-user and the effective group ID 
of the process does not match the group ID of the file, mode bit 02000 (set group 
ID on execution) is cleared. 

If a 410 executable file has the sticky bit (mode bit 01000) set, the operating sys- 
tem will not delete the program text from the swap area when the last user pro- 
cess terminates. If a 413 executable file has the sticky bit set, the operating sys- 
tem will not delete the program text from memory when the last user process ter- 
minates. In either case, if the sticky bit is set the text will already be available 
(either in a swap area or in memory) when the next user of the file executes it, 
thus making execution faster. 

If the executing process is not owned by the super-user, chmod will mask the 
sticky-bit but will not return an error. 

If a directory is writable and has the sticky bit set, files within that directory can 
be removed only if one or more of the following is true Isee unlink(2)l: 

the user owns the file 
the user owns the directory 
the file is writable by the user 
the user is the super-user 

If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010 
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(execute or search by group) is not set, mandatory file/record locking will exist 
on a regular file. This may effect future calls to open(2), creat(2), read(2), and 
write(2) on this file. 

chxnod will fail and the file mode will be imchanged if one or more of the follow- 
ing are true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID does not match the owner of the file and the 

effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTRl A signal was caught during the chxnod system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

lEMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chown(2), creat(2), f cntl(2), inknod(2), open(2), read(2), write(2). 
chmodd) in the User's Reference Manual 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of ~1 is 
returned and errno is set to indicate the error. 
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NAME 

chown - change owner and group of a file 

SYNOPSIS 

int chown (path, owner, group) 

char *path; 

int owner, group; 

DESCRIPTION 

path points to a path name naming a file. The owner ID and group ID of the 
namal file are set to the numeric values contained in owner and group respec- 
tively. 

Only processes with effective user ID equal to the file owner or super-user may 
change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set-group-ID 
bits of the file mode, 04000 and 02000 respectively, will be cleared. 

chown will fail and the owner and group of the named file will remain 
unchanged if one or more of the following are true: 

lENOTDIRl A component of the path prefix is not a directory. 

[ENOENTJ The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID does not match the owner of the file and the 

effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTRl A signal was caught during the chown system call. 

lENOLINKl path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chniDd(2). 

chown(l) in the User's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

chroot - change root directory 

SYNOPSIS 

int chroot (path) 
char *path; 

DESCRIPTION 

path points to a path name naming a directory, chroot causes the named direc- 
tory to become the root directory, the starting point for path searches for path 
names beginning with /. The user's working directory is unaffected by the 
chroot system call. 

The effective user ID of the process must be super-user to change the root direc- 
tory. 

The . . entry in the root directory is interpreted to mean the root directory itself. 
Thus, . . cannot be used to access files outside the subtree rooted at the root 
directory. 

chroot will fail and the root directory will remain unchanged if one or more of 
the following are true: 

[ENOTDIR] Any component of the path name is not a directory. 
[ENOENTl The named directory does not exist. 
[EPERM] The effective user ID is not super-user. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the chroot system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chdir(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

close - close a file descriptor 

SYNOPSIS 

int close (fildes) 
int fildes; 

DESCRIPTION 

fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system 
call, close closes the file descriptor indicated by fildes. All outstanding record 
locks owned by the process (on the file indicated by fildes) are removed. 

If a STREAMS [see intro(2)] file is closed, and the calling process had previously 
registered to receive a SIGPOLL signal [see signal(2) and sigset(2)] for events 
associated with that file [see I SETSIG in streamio(7)], the calling process will be 
unregistered for events associated with the file. The last close for a stream 
causes the stream associated with fildes to be dismantled. If O^NDELAY is not set 
and there have been no signals posted for the stream, close waits up to 15 
seconds, for each module and driver, for any output to drain before dismantling 
the stream. If the O NDELAY flag is set or if there are any pending signals, close 
does not wait for output to drain, and dismantles the stream immediately. 

The named file is closed imless one or more of the following are true: 

[EBADF] fildes is not a valid open file descriptor. 

[EINTR] A signal was caught during the close system call. 

[ENOLINK] fildes is on a remote machine and the link to that machine is no 
longer active. 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), intro(2), open(2), pipe(2), signal(2), sig~ 
set(2). 

streamio(7) in the System Administrate/ s Reference Manual 
DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

creat - create a new file or rewrite an existing one 

SYNOPSIS 

int creat (path, xnode) 
char ♦path; 
int mode; 

DESCRIPTION 

creat creates a new ordinary file or prepares to rewrite an existing file named by 
the path name pointed to by path. 

If the file exists, the length is truncated to 0 and the mode and owner are 
unchanged. Otherwise, the file's owner ID is set to the effective user ID, of the 
process the group ID of the process is set to the effective group ID, of the process 
and the low-order 12 bits of the file mode are set to the value of mode modified 
as follows: 

All bits set in the process's file mode creation mask are cleared [see 
uxnask(2)]. 

The "save text image after execution bit" of the mode is cleared [see 
chxtiod(2)l. 

Upon successful completion, a write-only file descriptor is returned and the file is 
open for writing, even if the mode does not permit writing. The file pointer is set 
to the beginning of the file. The file descriptor is set to remain open across exec 
system calls [see fcntl(2)]. No process may have more than 20 files open simul- 
taneously. A new file may be created with a mode that forbids writing. 

creat fails if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[ENOENTl The path name is null. 

[EACCES] The file does not exist and the directory in which the file is to be 

created does not permit writing. 

[EROFS] The named file resides or would reside on a read-only file sys- 

tem. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being exe- 
cuted. 

[EACCES] The file exists and write permission is denied. 

[EISDIR] The named file is an existing directory. 

[EMHLE] NOFILES file descriptors are currently open. 

[EFAULT] path points outside the allocated address space of the process. 

[ENRLE] The system file table is full. 
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[EAGAIN] The file exists, mandatory file/record locking is set, and there are 
outstanding record locks on the file [see chinod(2)]. 

[EINTR] A signal was caught during the creat system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 



The file system is out of inodes. 
close(2), dup(2), fcntl(2), lseek(2), qpen(2), read(2), uinask(2). 



[ENOSPC] 

SEE ALSO 

chiiic)d(2), 
write(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of -1 is returned and ermo is set to indicate the 
error. 
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NAME 

dup - duplicate an open file descriptor 

SYNOPSIS 

int dup (£ildes) 
int fildes; 

DESCRIPTION 

fildes is a file descriptor obtained ft"om a creat, open, dup, fcntl, or pipe system 
call, dup returns a new file descriptor having the following in common with the 
original: 

Same open file (or pipe). 

Same file pointer (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/write). 

The new file descriptor is set to remain open across exec system calls [see 
fcntl(2)]. 

The file descriptor returned is the lowest one available. 

dup will fail if one or more of the following are true: 

[EBADF] fildes is not a valid open file descriptor. 

[EINTR] A signal was caught during the dup system call. 

[EMFILE] NOFILES file descriptors are currently open. 

[ENOLINKl fildes is on a remote machine and the link to that machine is no 
longer active. 

SEE ALSO 

close(2), creat(2), exec(2), fcntl(2), open(2), pipe(2), lockf (3C). 
DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of -1 is returned and errno is set to indicate the 
error. 
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NAME 

exec; execl, execv, execle, execve, execlp, execvp - execute a file 
SYNOPSIS 

int execl (path, argO, argl, argn, (char *)0) 

char *path, *argO, ♦argl, ♦argn; 

int execv (path, argv) 
char *path, *argv[ ] ; 

int execle (path, argO, argl, argn, (char *)0, envp) 

char *path, *argO, *argl, *argn, *envp[ ]; 

int execve (path, argv, envp) 
char *path, *argv[ ], *envp[ ]; 

int execlp (file, argO, argl, argn, (char *)0) 

char *file, *argO, *argl, *argn; 

int execvp (file, argv) 
char *file, *argv[ ]; 

DESCRIPTION 

exec in all its forms transforms the calling process into a new process. The new 
process is constructed from an ordinary, executable file called the new process file. 
This file consists of a header [see a.out(4)], a text segment, and a data segment. 
The data segment contains an initialized portion and an iminitialized portion 
(bss). There can be no return from a successful exec because the calling process 
is overlaid by the new process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int curgc; 

char **argv, **envp; 

where argc is the argument coimt, argo is an array of character pointers to the 
arguments themselves, and envp is an array of character pointers to the environ- 
ment strings. As indicated, argc is conventionally at least one and the first 
member of the array points to a string containing the name of the file. 

path points to a path name that identifies the new process file. 

file points to the new process file. The path prefix for this file is obtained by a 
search of the directories passed as the environment line "PATH =" [see 
environ(5)]. The environment is supplied by the shell [see sh(l)]. 

argO, argl, ... , argn are pointers to null-terminated character strings. These 
strings constitute the argument list available to the new process. By convention, 
at least argO must be present and point to a string that is the same as path (or its 
last component). 

argv is an array of character pointers to null-terminated strings. These strings 
constitute the argument list available to the new process. By convention, argv 
must have at least one member, and it must point to a string that is the same as 
path (or its last component), argv is terminated by a null pointer. 
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enz^ is an array of character pointers to null-terminated strings. These strings 
constitute the environment for the new process, envp is terminp^ted by a null 
pointer. For execl and execv, the C run-time start-off routine places a pointer to 
the environment of the calling process in the global cell: 

extern char * ♦environ; 

and it is used to pass the environment of the calling process to the new process. 

File descriptors open in the calling process remain open in the new process, 
except for those whose close-on-exec flag is set; see fcntl(2). For those file 
descriptors that remain open, the file pointer is unchanged. 

Signals set to terminate the calling process will be set to terminate the new pro- 
cess. Signals set to be ignored by the calling process will be set to be ignored by 
the new process. Signals set to be caught by the calling process will be set to ter- 
minate new process; see signal(2). 

For signals set by sigset(2), exec will ensure that the new process has the same 
system signal action for each signal type whose action is SIG DFL, SIG IGN, or 
SIG^HOLD as the calling process. However, if the action is to catch the signal, 
then the action will be reset to SIG DFL, and any pending signal for this type 
will be held. 

If the set-user-ID mode bit of the new process file is set [see chmod(2)], exec sets 
the effective user ID of the new process to the owner ID of the new process file. 
Similarly, if the set -group-ID mode bit of the new process file is set, the effective 
group ID of the new process is set to the group ID of the new process file. The 
real user ID and real group ID of the new process remain the same as those of the 
calling process. However, if the effective user-ID is root or Super-user, the set- 
user-ID and set-group-ID bits will be honored when the process is being con- 
trolled by ptrace(2). 

The shared memory segments attached to the calling process will not be attached 
to the new process [see shmop(2)]. 

Profiling is disabled for the new process; see prof il(2). 

The new process also inherits the following attributes from the calling process: 

nice value [see nice(2)] 

process ID 

parent process ID 

process group ID 

semadj values [see sempp(2)] 

tty group ID [see exit(2) and signal(2)] 

trace flag [see ptrace(2) request 01 

time left until an alarm clock signal [see alarxn(2)] 

current working directory 

root directory 

file mode creation mask [see uinask(2)l 
file size limit [see ulimit(2)] 
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utiine/ stixne, cutime, and stime [see tiine8(2)] 
file-locks [see fcntl(2) and lockf (3C)] 

exec will fail and return to the calling process if one or more of the following are 
true: 

[ENOENT] One or more components of the new process path name of the 
file do not exist. 

[ENOTDIR] A component of the new process path of the file prefix is not a 
directory. 

[EACCESl Search permission is denied for a directory listed in the new pro- 

cess file's path prefix. 

[EACCES] The new process file is not an ordinary file. 

[EACCES] The new process file mode denies execution permission. 

[ENOEXEC] The exec is not an execlp or execvp, and the new process file 
has the appropriate access permission but an invalid magic 
number in its header. 

[ETXTBSY] The new process file is a pure procedure (shared text) file that is 
currently open for writing by some process. 

[ENOMEM] The new process requires more memory than is allowed by the 
system-imposed maximum MAXMEM. 

[E2BIG] The number of bytes in the new process's argument list is greater 

than the system-imposed limit of 5120 bytes. 

[EFAULT] Required hardware is not present. 

[EFAULTl An a.out that was compiled with the MAU or 32B flag is rimning 

on a machine without a MAU or 32B. 

[EFAULT] path, argv, or envp point to an illegal address. 

[EAGAIN] Not enough memory. 

[ELIBACC] Required shared library does not have execute permission. 

[ELIBEXEq Trying to exec a shared library directly. 

[EINTR] A signal was caught during the exec system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

alanrt[2), exit(2), fcntl(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), 
sigset(2), times(2), uliinit(2), uinask(2), lockf (3C), a.out(4), environ(5). 
sh(l) in the User's Reference Manual 

DIAGNOSTICS 

If exec returns to the calling process an error has occurred; the return value will 
be -1 and errno will be set to indicate the error. 
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NAME 

exit, _exit - terminate process 

SYNOPSiS 

void exit (status) 
int status; 
void __exit (status) 
int status; 

DESCRIPTiON 

exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait, it is notified of the 
calling process's termination and the low order eight bits (i.e., bits 0377) of status 
are made available to it [see wait(2)]. 

If the parent process of the calling process is not executing a wait, the calling 
process is transformed into a zombie process. A zombie process is a process that 
only occupies a slot in the process table. It has no other space allocated either in 
user or kernel space. The process table slot that it occupies is partially overlaid 
with time accounting information (see <3ys/proc . h>) to be used by times. 

The parent process ID of all of the calling processes' existing child processes and 
zombie processes is set to 1. This means the initialization process [see intro(2)] 
inherits each of these processes. 

Each attached shared memory segment is detached and the value of shm_nattach 
in the data structure associated with its shared memory identifier is decremented 
by 1. 

For each semaphore for which the calling process has set a semadj value [see 
seinop(2)], that semadj value is added to the semval of the specified semaphore. 

If the process has a process, text, or data lock, an unlock is performed [see 
plock(2)]. 

An accounting record is written on the accounting file if the system's accounting 
routine is enabled [see acct(2)]. 

If the process ID, tty group ID, and process group ID of the calling process are 
equal, the SIGHUP signal is sent to each process that has a process group ID equal 
to that of the calling process. 

A death of child signal is sent to the parent. 

The C function exit may cause cleanup actions before the process exits. The 
function _exit circumvents all cleanup. 

SEE ALSO 

acct(2), intro(2), plock(2), semop(2), signal(2), sigset(2), wait(2). 
DIAGNOSTICS 

None. There can be no return from an exit system call. 
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NAME 

f cntl ~ file control 

SYNOPSIS 

♦include <fcntl.h> 

int fcntl (fildes, cind, arg) 
int fildes, csnd, arg; 

DESCRIPTION 

fcntl provides for control over open files, fildes is an open file descriptor [see 
intro(2)]. 

The data type, value and use of arg are specific to the value of and. cmd specifies 
the operation to be performed by fcntl and may be one of the following: 

F_DUPFD Return a new file descriptor as follows: 

Lowest numbered available file descriptor greater than or equal 
to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors 
share one file pointer). 

Same access mode (read, write or read/ write). 

Same file status flags (i.e., both file descriptors share the same 
file status flags) - 

The closeK)n-exec flag (see F GETFD) associated with the new 
file descriptor is set to remain open across exec(2) system calls. 

F GETFD Get the close-on-exec flag associated with fildes. If the low- 

order bit is 0, the file will remain open across exec. Otherwise, 
the file will be closed upon execution of exec. 

F SETFD Set the close-on-exec flag associated with fildes to the low-order 

bit of arg (0 or 1 as above). 

F_GETFL Get fildes status flags. 

F^SETFL Set fildes status flags to arg. Only certain flags can be set [see 

fcntl(5)]. 

F GETLK Get the first lock which blocks the lock description given by the 

variable of type struct flock pointed to by arg. The information 
retrieved overwrites the information passed to fcntl in the flock 
structure. If no lock is found that would prevent this lock from 
being created, then the structure is passed back unchanged 
except for the lock type which will be set to FJJNLCK. 

F^SETLK Set or clear a file segment lock according to the variable of type 

struct flock pointed to by arg [see fcntl(5)]. The cmd F_SETLK is 
used to establish read (F^RDLCK) and write (F^WRLCK) locks, as 
well as remove either type of lock (FJJNLCK). If a read or 
write lock cannot be set, fcntl will return immediately with an 
error value of -1. 
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F__SETLKW This cmd is the same as F__SETLK except that if a read or write 

lock is blocked by other locks, fcntl will block until the seg- 
ment is free to be locked. 

A read lock prevents any process from write locking the protected area. More 
than one read lock may exist for a given segment of a file at a given time. The 
file descriptor on which a read lock is being placed must have been opened with 
read access. 

A write lock prevents any process from read locking or write locking the pro- 
tected area. Only one write lock may exist for a given segment of a file at a 
given time. The file descriptor on which a write lock is being placed must have 
been opened with write access. 

The flock structure describes the type il_type), starting offset (Ijvhence), relative 
offset (l_start), size (l ien), process id (l_pid), and RFS system id (I sysid) of the 
segment of the file to be affected. The process id and system id fields are used 
only with the F GETLK cmd to return the values for a blocking lock. Locks may 
start and extend beyond the current end of a file, but may not be negative rela- 
tive to the beginning of the file. A lock may be set to always extend to the end of 
file by setting IJen to zero (0). If such a lock also has Ijvhence and Ijtart set to 
zero (0), the whole file will be locked. Changing or unlocking a segment from 
the middle of a larger locked segment leaves two smaller segments for either end. 
Locking a segment that is already locked by the calling process causes the old 
lock type to be removed and the new lock type to take effect. All locks associ- 
ated with a file for a given process are removed when a file descriptor for that 
file is closed by that process or the process holding that file descriptor terminates. 
Locks are not inherited by a child process in a f ork(2) system call. 

When mandatory file and record locking is active on a file [see ch2nDd(2)], read(2) 
and write(2) system calls issued on the file will be affected by the record locks in 
effect. 

fcntl will fail if one or more of the following are true: 



[EBADF] fildes is not a valid open file descriptor. 

[EBADFl cmd is F_SETLK or F_SETLKW , the type of lock (Ijype) is a read 

lock (F RDLCK) and fildes is not a valid open file descriptor open 
for reading. 

[EBADFl cmd is F SETLK or F SETLKW , the type of lock (Ijype) is a write 

lock (F^WRLCK) and fildes is not a valid open file descriptor open 
for writing. 

[EMFILEl cmd is F DUPFD and the number of file descriptors currently 

open in the calling process is the configured value for the max- 
imum number of open file descriptors allowed each user. 

[EINVAL] cmd is F DUPFD and arg is either negative, or greater than or 

equal to the configured value for the maximum number of open 
file descriptors allowed each user. 
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[EDSrVAL] 
[EINVAL] 

[EACCES] 



[ENOLCK] 



[EDEADLK] 



[EFAULT] 



cmd is not a valid value. 

cmd is F_GETLK, F_SETLK, or F_SETLKW and arg or the data it 
points to is not valid. 

cmd is F SETLK, the type of lock (IJype) is a read (F RDLCK) lock 
and the segment of a file to be locked is already write locked by 
another process or the type is a write (F_WRLCK) lock and the 
segment of a file to be locked is already read or write locked by 
another process. 

cmd is F^^SETLK or F SETLKW, the type of lock is a read or write 
lock, and there are no more record locks available (too many file 
segments locked) because the system maximum has been 
exceeded. 

cmd is F SETLKW, the lock is blocked by some lock from another 
process, and if f cntl blocked the calling process waiting for that 
lock to become free, this would cause a deadlock. 



cmd is F GETLK, F SETLK or F SETLKW and the value pointed to 
by arg resulted in an address outside the program address space. 

[EINTR] A signal was caught during the f cntl system call. 

[ENOLINK] fildes is on a remote machine and the link to that machine is no 
longer active. 

SEE ALSO 

fcntl(5). 

close(2), creat(2), dup(2), exec(2), f ork(2), open(2), pipe(2). 
DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 
F__DUPFD A new file descriptor. 

F__GETFD Value of flag (only the low-order bit is defined). 

F_SETFD Value other than -1. 

F GETFL Value of file status flags. 

F SETFL Value other than - 1 . 

F GETLK Value other than - 1 . 

F_SETLK Value other than - 1 . 

F^SETLKW Value other than - 1. 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 

Because, in the future, the variable ermo will be set to EAGAIN rather than 
EACCES when a section of a file is already locked by another process, portable 
application programs should expect and test for either value. 
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NAME 

fork - create a new process 

SYNOPSIS 

int fork () 

DESCRIPTION 

fork causes creation of a new process. The new process (child process) is an 
exact copy of the calling process (parent process). This means the child process 
inherits the following attributes from the parent process: 

environment 

close-on-exec flag [see exec(2)] 

signal handling settings (i.e., SIGJDFU SIG_IGN, SiGjiOLD, function 
address) 

set-user-ID mode bit 
set-group-ID mode bit 
profiling on/off status 
nice value [see nice(2)] 

all attached shared memory segments [see shmop(2)] 

process group ID 

tty group ID [see exit(2)] 

current working directory 

root directory 

file mode creation mask [see uinask(2)] 
file size limit [see ulimit(2)] 

The child process differs from the parent process in the following ways: 

The child process has a imique process ID. 

The child process has a different parent process ID (i.e., the process ID of 
the parent process). 

The child process has its own copy of the parent's file descriptors. Each 
of the child's file descriptors shares a common file pointer with the 
corresponding file descriptor of the parent. 

All semadj values are cleared [see semop(2)]. 

Process locks, text locks and data locks are not inherited by the child [see 
plock(2)]. 

The child process's utime, stime, cutime, and cstime are set to 0. The 
time left until an alarm clock signal is reset to 0. 

fork will fail and no child process will be created if one or more of the following 
are true: 

[EAGAINl The system-imposed limit on the total number of processes under 

execution would be exceeded. 

[EAGAINl The system-imposed limit on the total number of processes under 

execution by a single user would be exceeded. 
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[EAGAIN] Total amount of system memory available when reading via raw 

lO is temporarily insufficient. 

SEE ALSO 

exec(2), nice(2), plock(2), ptrace(2), senpp(2), shinDp(2), signal(2), sigset(2), 
tiines(2), uliinit(2), uinask(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, fork returns a value of 0 to the child process and 
returns the process ID of the child process to the parent process. Otherwise, a 
value of -1 is returned to the parent process, no child process is created, and 
errno is set to indicate the error. 
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NAME 

getdents - read directory entries and put in a file system independent format 

SYNOPSIS 

♦include <sys/dirent . h> 

int getdents (fildes, buf, nbyte) 
int fildes; 
char *buf ; 
unsigned nbyte; 

DESCRIPTION 

fildes is a file descriptor obtained ft-om an open(2) or dup(2) system call. 

getdents attempts to read nbyte bytes from the directory associated with fildes 
and to format them as file system independent directory entries in the buffer 
pointed to by buf. Since the file system independent directory entries are of vari- 
able length, in most cases the actual number of bytes returned will be strictly less 
than nbyte. 

The file system independent directory entry is specified by the dirent structure. 

On devices capable of seeking, getdents starts at a position in the file given by 
the file pointer associated with fildes. Upon return from getdents, the file 
pointer is incremented to point to the next directory entry. 

This system call was developed in order to implement the readdir routine [for a 
description see directory(3C)], and should not be used for other purposes. 

getdents will fail if one or more of the following are true: 

[EBADFJ fildes is not a valid file descriptor open for reading. 

[EFAULT] buf points outside the allocated address space. 

[EINVAL] nbyte is not large enough for one directory entry. 

[ENOENT] The current file pointer for the directory is not located at a valid 

entry. 

[ENOLINK] fildes points to a remote machine and the link to that machine is 
no longer active. 

[ENOTDIR] fildes is not a directory. 

[EIO] An I/O error occurred while accessing the file system. 

SEE ALSO 

directory(3C). 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating the 
number of bytes actually read. A value of 0 indicates the end of the directory has 
been reached. If the system call failed, a -1 is returned and ermo is set to indi- 
cate the error. 
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NAME 

getmsg - get next message off a stream 

SYNOPSIS 

♦include <stropts.h> 

int get:insg(fd, ctlptr, dataptr^ flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int *flags; 

DESCRIPTION 

getmsg retrieves the contents of a message [see intro(2)] located at the stream 
head read queue from a STREAMS file, and places the contents into user specified 
buffer(s). The message must contain either a data part, a control part or both. 
The data and control parts of the message are placed into separate buffers, as 
described below. The semantics of each part is defined by the STREAMS module 
that generated the message. 

fd specifies a file descriptor referencing an open stream, ctlptr and dataptr each 
point to a strbuf structure which contains the following members: 

int maxlen; /* maximum buffer lengtJi */ 
int len; /* lengt:h of data */ 
char *buf ; /* ptr to buffer */ 

where buf points to a buffer in which the data or control information is to be 
placed, and maxlen indicates the maximum number of bytes this buffer can hold. 
On return, len contains the number of bytes of data or control information actu- 
ally received, or is 0 if there is a zero-length control or data part, or is -1 if no 
data or control information is present in the message, flags may be set to the 
values 0 or RS_HIPRI and is used as described below. 

ctlptr is used to hold the control part from the message and dataptr is used to 
hold the data part from the message. If ctlptr (or dataptr) is NULL or the maxlen 
field is -1, the control (or data) part of the message is not processed and is left on 
the stream head read queue and len is set to -1. If the maxlen field is set to 0 and 
there is a zero-length control (or data) part, that zero-length part is removed from 
the read queue and len is set to 0. If the maxlen field is set to 0 and there are 
more than zero bytes of control (or data) information, that information is left on 
the read queue and len is set to 0. If the maxlen field in ctlptr or dataptr is less 
than, respectively, the control or data part of the message, maxlen bytes are 
retrieved. In this case, the remainder of the message is left on the stream head 
read queue and a non-zero return value is provided, as described below under 
DIAGNOSTICS. If information is retrieved from a priority message, flags is set to 
RS HIPRI on return. 

By default, getmsg processes the first priority or non-priority message available 
on the stream head read queue. However, a user may choose to retrieve only 
priority messages by setting flags to RS_HIPRI. In this case, get^msg will only pro- 
cess the next message if it is a priority message. 
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If O NDELAY has not been set, get:insg blocks until a message, of the type(s) 
specified by flags (priority or either), is available on the stream head read queue. If 
O NDELAY has been set and a message of the specified type(s) is not present on 
the read queue, get^msg fails and sets ermo to EAGAIN. 

If a hangup occurs on the stream from which messages are to be retrieved, 
getmsg will continue to operate normally, as described above, until the stream 
head read queue is empty. Thereafter, it will return 0 in the hn fields of ctljjtr and 
dataptr. 

getmsg fails if one or more of the following are true: 

[EAGAIN] The OJsIDELAY flag is set, and no messages are available. 

[EBADF] fd is not a valid file descriptor open for reading. 

[EBADMSG] Queued message to be read is not valid for get:xnsg. 

[EFAULT] ctlptr, dataptr, or flags points to a location outside the allocated 

address space. 

[EINTR] A signal was caught during the getmsg system call. 

[EINVAL] An illegal value was specified in flags, or the stream referenced by 

fd is linked under a multiplexor. 

[ENOSTR] A stream is not associated with fd. 

A getmsg can also fail if a STREAMS error message had been received at the 
stream head before the call to getunsg. The error returned is the value contained in 
the STREAMS error message. 

SEE ALSO 

intro(2), read(2), poll(2), putrosg(2), write(2). 

STREAMS Pnmer 

STREAMS Programmer's Guide 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A value of 0 indi- 
cates that a full message was read successfully. A return value of MORECTL indi- 
cates that more control information is waiting for retrieval. A return value of 
MOREDATA indicates that more data is waiting for retrieval. A return value of 
MORECTL I MOREDATA indicates that both types of information remain. Subse- 
quent getmsg calls will retrieve the remainder of the message. 
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NAME 

getpid, getpgrp, getppid - get process, process group, and parent process IDs 

SYNOPSIS 

int getpid ( ) 

int getpgrp ( ) 

int getppid ( ) 

DESCRIPTION 

getpid returns the process ID of the calling process. 

getpgrp returns the process group ID of the calling process, 
getppid returns the parent process ID of the calling process. 
SEE ALSO 

exec(2), for)c(2), intro(2), setpgrp(2), signal(2). 
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NAME 

getuid, geteuid, getgid, getegid ~ get real user, effective user, real group, and 
effective group IDs 

SYNOPSIS 

unsigned short getuid ( ) 

unsigned short geteuid ( ) 

unsigned short getgid ( ) 

unsigned short getegid ( ) 

DESCRIPTION 

getuid returns the real user ID of the calling process, 
geteuid returns the effective user ID of the calling process, 
getgid returns the real group ID of the calling process, 
getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

icx:tl - control device 

SYNOPSIS 

int ioctl (fildes, request, arg) 
int fildeSr request; 

DESCRIPTION 

ioctl performs a variety of control functions on devices and STREAMS. For 
non-STREAMS files, the functions performed by this call are device-specific control 
fimctions. The arguments request and arg are passed to the file designated by 
fildes and are interpreted by the device driver. This control is infrequently used 
on non-STREAMS devices, with the basic input/output functions performed 
through the read(2) and write(2) system calls. 

For STREAMS files, specific functions are performed by the ioctl call as described 
in streamio(7). 

fildes is an open file descriptor that refers to a device, request selects the control 
function to be performed and will depend on the device being addressed, arg 
represents additional information that is needed by this specific device to perform 
the requested fimction. The data type of arg depends upon the particular control 
request, but it is either an integer or a pointer to a device-specific data structure. 

In addition to device-specific and STREAMS fimctions, generic fimctions are pro- 
vided by more than one device driver, for example, the general terminal interface 
[see termio(7)]. 

ioctl will fail for any type of file if one or more of the following are true: 
[EACCES] Future error. 

[EBADF] fildes is not a valid open file descriptor. 

[ENOTTY] fildes is not associated with a device driver that accepts control 
functions. 

[EINTR] A signal was caught during the ioctl system call. 

ioctl will also fail if the device driver detects an error. In this case, the error is 
passed through ioctl without change to the caller. A particular driver might not 
have all of the following error cases. Other requests to device drivers will fail if 
one or more of the following are true: 

[EFAULT] request requires a data transfer to or from a buffer pointed to by 
arg, but some part of the buffer is outside the process's allocated 
space. 

[EINVAL] request or arg is not valid for this device. 
[EIO] Some physical I/O error has occurred. 

[ENXIO] The request and arg are valid for this device driver, but the ser- 

vice requested can not be performed on this particular subdevice. 
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[ENOLINK] fildes is on a remote machine and the link to that machine is no 
longer active. 

STREAMS errors are described in streainio(7). 

SEE ALSO 

streainio(7), termio(7) in the System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion, the value returned depends upon the device control 
function, but must be a non-negative integer. Otherwise, a value of -1 is returned 
and errno is set to indicate the error. 
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NAME 

kill - send a signal to a process or a group of processes 

SYNOPSIS 

int kill (pid, sig) 
int pid^ sig; 

DESCRIPTION 

kill sends a signal to a process or a group of processes. The process or group 
of processes to which the signal is to be sent is specified by pid. The signal that 
is to be sent is specified by sig and is either one from the list given in signal (2), 
or 0. If sig is 0 (the null signal), error checking is performed but no signal is 
actually sent. This can be used to check the validity of pid. 

The real or effective user ID of the sending process must match the effective or 
saved effective ID [from exec(2)] user ID of the receiving process, unless the effec- 
tive user ID of the sending process is super-user. 

The processes with a process ID of 0 and a process ID of 1 are special processes 
[see intro(2)] and will be referred to below as procO and prod, respectively. 

If pid is greater than zero, sig will be sent to the process whose process ID is 
equal to pid. pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod whose pro- 
cess group ID is equal to the process group ID of the sender. 

If pid is -1 and the effective user ID of the sender is not super-user, sig will be 
sent to all processes excluding procO and prod whose real user ID is equal to the 
effective user ID of the sender. 

If pid is -1 and the effective user ID of the sender is super-user, sig will be sent to 
all processes excluding procO and prod . 

If pid is negative but not -1, sig will be sent to all processes whose process group 
ID is equal to the absolute value of pid. 

kill will fail and no signal will be sent if one or more of the following are true: 
[EINVAL] sig is not a valid signal number. 
[EINVAL] sig is SIGKILL and pid is 1 (procl). 

[ESRCH] No process can be found corresponding to that specified by pid. 

[EPERM] The user ID of the sending process is not super-user, and its real 

or effective user ID does not match the real or effective user ID of 
the receiving process. 

SEE ALSO 

getpid(2), setpgrp(2), signal(2), sigset(2). 
kill(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

link - link to a file 

SYNOPSIS 

int link (pathl, path2) 
char *pathlr *path2; 

DESCRIPTION 

pathl points to a path name naming an existing file, path! points to a path name 
naming the new directory entry to be created, link creates a new link (directory 
entry) for the existing file. 

link will fail and no link will be created if one or more of the following are true: 

[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENn A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permission. 

[ENOENT] The file named by pathl does not exist. 

[EEXISTl The link named by path2 exists. 

[EPERM] The file named by pathl is a directory and the effective user ID is 

not super-user. 

[EXDEV] The link named by path! and the file named by pathl are on dif- 

ferent logical devices (file systems). 

[ENOENT] pathl points to a null path name. 

[EACCES] The requested link requires writing in a directory with a mode 

that denies write permission. 

[EROFS] The requested link requires writing in a directory on a read-only 

file system. 

[EFAULT] path points outside the allocated address space of the process. 

[EMLINK] The maximum number of links to a file would be exceeded. 

[EINTR] A signal was caught during the link system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

unlink(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

Iseek - move read /write file pointer 
SYNOPSIS 

long Iseek (fildes, offset^ whence) 
int fildes; 
long offset; 
int Krtience; 

DESCRIPTION 

fildes is a file descriptor returned from a creat, open, dap, or fcntl system call. 
Iseek sets the file pointer associated with fildes as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location plus offset. 

If whence is 2, the pointer is set to the size of the file plus offset. 

Upon successful completion, the resulting pointer location, as measured in bytes 
from the beginning of the file, is returned. Note that if fildes is a remote file 
descriptor and offset is negative, Iseek will return the file pointer even if it is 
negative. 

Iseek will fail and the file pointer will remain unchanged if one or more of the 
following are true: 

[EBADF] fildes is not an open file descriptor. 

[ESPIPE] fildes is associated with a pipe or fifb. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

[EINVAL] fildes is not a remote file descriptor, and the resulting file pointer 
would be negative. 

Some devices are incapable of seeking. The value of the file pointer associated 
with such a device is undefined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), cpen(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer indicating the file pointer 
value is returned. Otherwise, a value of -1 is returned and ermo is set to indicate 
the error. 
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NAME 

xnkdir - make a directory 

SYNOPSIS 

int nikdir (path^ mode) 
char *path; 
int node; 

DESCRIPTION 

The routine mkdir creates a new directory with the name path. The mode of the 
new directory is initialized from the mode. The protection part of the mode argu- 
ment is modified by the process's mode mask [see umask(2)]. 

The directory's owner ID is set to the process's effective user ID. The directory's 
group ID is set to the process's effective group ID. The newly created directory is 
empty with the possible exception of entries for and inkdir will fail and 
no directory will be created if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

[EACCES] Either a component of the path prefix denies search permission 

or write permission is denied on the parent directory of the 
directory to be created. 

[ENOENT] The path is longer than the maximum allowed. 

[EEXIST] The named file already exists. 

[EROFS] The path prefix resides on a read-only file system. 

[EFAULT] path points outside the allocated address space of the process. 

[EMLINK] The maximum number of links to the parent directory would be 

exceeded. 

[EIO] An I/O error has occurred while accessing the file system. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned, and ermo is set to indicate the error. 
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NAME 



iriknod - make a directory, or a special or ordinary file 



SYNOPSIS 



int xnknod (path, mode, dev) 
char *path; 
int node, dev; 



DESCRIPTION 



Iriknod creates a new file named by the path name pointed to by path. The mode 
of the new file is initialized from mode. Where the value of mode is interpreted as 
follows: 

0170000 file type; one of the following: 

0010000 fifo special 

0020000 character special 

0040000 directory 

0060000 block special 

0100000 or 0000000 ordinary file 

0004000 set user ID on execution 

00020#0 set group ID on execution if # is 7, 5, 3, or 1 

enable mandatory file/record locking if # is 6, 4, 2, or 0 
0001000 save text image after execution 
0000777 access permissions; constructed from the following: 

0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
(X)00070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 

The owner ID of the file is set to the effective user ID of the process. The group 
ID of the file is set to the effective group ID of the process. 

Values of mode other than those above are undefined and should not be used. 
The low-order 9 bits of mode are modified by the process's file mode creation 
mask: all bits set in the process's file mode creation mask are cleared [see 
uxnask(2)]. If mode indicates a block or character special file, dev is a 
configuration-dependent specification of a character or block I/O device. If mode 
does not indicate a block special or character special device, dev is ignored. 

xnknod may be invoked only by the super-user for file types other than FIFO spe- 



mknod will fail and the new file will not be created if one or more of the follow- 
ing are true: 



cial. 



[EPERM] 
[ENOTDIRl 



The effective user ID of the process is not super-user. 
A component of the path prefix is not a directory. 
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[EEXISn 

[EFAULT] 

[ENOSPC] 

[EINTR] 

[ENOLINK] 



[ENOENT] 
[EROFS] 



A component of the path prefix does not exist. 

The directory in which the file is to be created is located on a 
read-only file system. 

The named file exists. 

path points outside the allocated address space of the process. 
No space is available. 

A signal was caught during the inknod system call. 

path points to a remote machine and the link to that machine is 
no longer active. 



[EMULTIHOP] Components of path require hopping to multiple remote 



SEE ALSO 

cdit!icxi(2), exec(2), uinask(2), f s(4). 
mkdird) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise^ a value of -1 is 
returned and errno is set to indicate the error. 



If inknod is used to create a device in a remote directory (Remote File Sharing), 
the major and minor device numbers are interpreted by the server. 



machines. 



NOTES 
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NAME 

mount - mount a file system 

SYNOPSIS 

♦include <sys/types.h> 
tinclude <sys/inount .h> 

int rooiant (spec, dir, mflag, fstyp, dataptr, datalen) 
char *spec, *dir; 
int xnflag, fstyp; 
char *dataptr; 
int datalen; 

DESCRIPTION 

mount requests that a removable file system contained on the block special file 
identified by spec be mounted on the directory identified by dir. spec and dir are 
pointers to path names, fstyp is the file system type number. The sysf s(2) sys- 
tem call can be used to determine the file system type number. Note that if both 
the MS_DATA and MS^FSS flag bits of mflag are off, the file system type will 
default to the root file system type. Only if either flag is on will fstyp be used 
to indicate the file system type. 

If the MS_DATA flag is set in mflag the system expects the dataptr and datalen 
arguments to be present. Together they describe a block of file-system specific 
data at address dataptr of length datalen. This is interpreted by file-system specific 
code within the operating system and its format depends upon the file system 
type. A particular file system type may not require this data, in which case 
dataptr and datalen should both be zero. Note that MS_FSS is obsolete and will be 
ignored if MS DATA is also set, but if MS FSS is set and MS DATA is not, 
dataptr and datalen are both asstimed to be zero. 

Upon successful completion, references to the file dir will refer to the root direc- 
tory on the mounted file system. 

The low-order bit of mflag is used to control write permission on the mounted file 
system; if 1, writing is forbidden, otherwise writing is permitted according to 
individual file accessibility. 

mount may be invoked only by the super-user. It is intended for use only by the 
mount(lM) utility. 

mount will fail if one or more of the following are true: 
[EPERM] The effective user ID is not super-user. 

[ENOENTl Any of the named files does not exist. 
[ENOTDIR] A component of a path prefix is not a directory. 
[EREMOTE] spec is remote and cannot be mounted. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 
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[ENOTBLK] 
[ENXIO] 
[ENOTDIR] 
[EFAULT] 

[EBUSY] 



spec is not a block special device. 

The device associated with spec does not exist. 

dir is not a directory. 

spec or dir points outside the allocated address space of the pro- 



cess. 



dir is currently mounted on, is someone's current working direc- 
tory, or is otherwise busy. 

[EBUSY] The device associated with spec is currently moimted. 

[EBUSY] There are no more mount table entries. 

[EROFS] spec is write protected and mflag requests write permission. 

[ENOSPC] The file system state in the super-block is not FsOKAY and mflag 

requests write permission, 

[EINVAL] The super block has an invalid magic number or the f styp is 

invalid or mflag is not valid. 

SEE ALSO 

sysfs(2), uinount(2). 

mount (IM), f s(4) in the System Administrator s Reference Manual. 
DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

xnsgctl - message control operations 

SYNOPSIS 

♦include <sys /types . h> 
♦include <sys/ipc.h> 
♦include <sys/msg.h> 

int msgctl (msqid, cmd, buf ) 
int msqid, cmd; 
struct msqidjds *buf ; 

DESCRIPTION 

msgctl provides a variety of message control operations as specified by cmd. 
The following cmds are available: 

IPC_STAT Place the current value of each member of the data structure 

associated with mscjid into the structure pointed to by buf. The 
contents of this structure are defined in intro(2). {READ} 

IPC__SET Set the value of the following members of the data structure 

associated with msqid to the corresponding value found in the 
structure pointed to by buf: 

msgjperm. uid 

insg_j>enn. gid 

insg_perm. node /* only low 9 bits */ 
msg__qbytes 

This cmd can only be executed by a process that has an effective 
user ID equal to either that of super user, or to the value of 
insg__penn.cuid or insgjperm.uid in the data structure associ- 
ated with msqid. Only super user can raise the value of 
xnsg_qbytes. 

IPC_RMID Remove the message queue identifier specified by msqid from the 

system and destroy the message queue and data structure associ- 
ated with it. This cmd can only be executed by a process that has 
an effective user ID equal to either that of super user, or to the 
value of msgjperm.cuid or msg__perm.uid in the data structure 
associated with msqid. 

msgctl will fail if one or more of the following are true: 

[EINVAL] msqid is not a valid message queue identifier. 

[EINVALl cmd is not a valid command. 

[EACCES] cmd is equal to IPC_STAT and {READ} operation permission is 

denied to the calling process [see intro(2)]. 

[EPERMl cmd is equal to IPC_RMID or IPCJSET. The effective user ID of the 

calling process is not equal to that of super user, or to the value 
of msgjperm.cuid or msg_j>erm.uid in the data structure associ- 
ated with msqid. 
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[EPERM] ctnd is equal to IPCJSET, an attempt is being made to increase to 

the value of xnsgjc^ytes, and the effective user ID of the calling 
process is not equal to that of super user. 

[EFAULT] buf points to an illegal address. 

SEE ALSO 

intro(2), insgget(2), xnsgpp(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

msgget -- get message queue 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ipc.h> 
♦include <sys/insg.h> 

int xnsgget (key, msgflg) 
key_t key; 
int msgflg; 

DESCRIPTION 

msgget returns the message queue identifier associated with key. 

A message queue identifier and associated message queue and data structure [see 
intro(2)] are created for key if one of the following are true: 

key is equal to IPCJPRIVME. 

key does not already have a message queue identifier associated with it, 
and (msgflg & ipcjCREAT) is "true". 

Upon creation, the data structure associated with the new message queue 
identifier is initialized as follows: 

msg_perm.cuid, rosg_perm.uid, msgjperm.cgid, and msgjperm.gid are 
set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of insg_perm.iticxie are set equal to the low-order 9 
bits of msgflg. 

n*sg_qnui!V msg^lspid, msg_lrpid, msg_stime, and msg_rtime are set 
equal to 0. 

msgjctime is set equal to the current time. 
msg_cf>ytes is set equal to the system limit, 
msgget will fail if one or more of the following are true: 

[EACCES] A message queue identifier exists for key, but operation permis- 

sion [see intro(2)] as specified by the low-order 9 bits of msgflg 
would not be granted. 

[ENOENT] A message queue identifier does not exist for key and (msgflg & 

IPCJCREAT) is "false". 

[ENOSPC] A message queue identifier is to be created but the system- 

imposed limit on the maximum number of allowed message 
queue identifiers system wide would be exceeded. 

[EEXISTI A message queue identifier exists for key but ((msgflg & 

IPCJCREAT) & (msgflg & IPC_EXCL)) is "true". 

SEE ALSO 

intro(2), msgctl(2), msgqp(2). 
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DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a message queue 
identifier, is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 
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NAME 

insgop - message operations 

SYNOPSIS 

finclude <sys/types.h> 
♦include <sys/ipc.h> 
finclude <sys/insg.h> 

int msgsnd (msqid, tnsgpf msgsz, insg£lg) 
int msqid; 

struct msgbuf *msgp; 
int xnsgsz, xnsgflg; 

int msgrcv (xnsqid, xnsgp, xnsgsz, msgtyp, xnsgflg) 
int msqid; 

struct msgbuf ♦msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 

DESCRIPTION 

msgsnd is used to send a message to the queue associated with the message 
queue identifier specified by msqid. {WRITE} msgp points to a structure containing 
the message. This structure is composed of the following members: 

long mtype; /* message type */ 
char mtext[]; /* message text */ 

mtype is a positive integer that can be used by the receiving process for message 
selection (see msgrcv below), mtext is any text of length msgsz bytes, msgsz can 
range from 0 to a system-imposed maximum. 

msgflg specifies the action to be taken if one or more of the following are true: 

The number of bytes already on the queue is equal to rosg_jcf>ytes [see 
intro(2)]. 

The total number of messages on all queues system-wide is equal to the 
system-imposed limit. 

These actions are as follows: 

If (msgflg & ipc_NOWAIT) is "true", the message will not be sent and the 
calling process will return immediately. 

If {msgflg & ipc_nowait) is "false", the calling process will suspend execu- 
tion until one of the following occurs: 

The condition responsible for the suspension no longer exists, in 
which case the message is sent. 

msqid is removed from the system [see msgctl(2)]. When this 
occurs, errno is set equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. In this 
case the message is not sent and the calling process resumes exe- 
cution in the manner prescribed in signal(2). 
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msgsnd will fail and no message will be sent if one or more of the following are 



true: 




[EINVAL] 


msqid is not a valid message queue identifier. 


[EACCES] 


Operation permission is denied to the calling process [see 




intro(2)]. 


[EINVAL] 


mtype is less than 1. 


[EAGAIN] 


The message cannot be sent for one of the reasons cited above 




and (msgflg & IPCJIOWAIT) is "true". 


[EINVAL] 


msgsz is less than zero or greater than the system-imposed limit. 


[EFAULT] 


msgp points to an illegal address. 



Upon successful completion, the following actions are taken with respect to the 
data structure associated with msqid [see intro (2)]. 

msgjqnum is incremented by 1. 

msg__lspid is set equal to the process ID of the calling process. 

msg_stixne is set equal to the current time. 

nisgrcv reads a message from the queue associated with the message queue 
identifier specified by msqid and places it in the structure pointed to by msgp. 
{READ} This structure is composed of the following members: 

long mtype; /* message type */ 
char mtext[]; /* message text */ 

mtype is the received message's type as specified by the sending process, mtext is 
the text of the message, msgsz specifies the size in bytes of mtext. The received 
message is truncated to msgsz bytes if it is larger than msgsz and (msgflg & 
M5G_NC«aRRaR) is "true". The truncated part of the message is lost and no indica- 
tion of the truncation is given to the calling process. 

msgtyp specifies the type of message requested as follows: 

If msgtyp is equal to 0, the first message on the queue is received. 

If msgtyp is greater than 0, the first message of type msgtyp is received. 

If msgtyp is less than 0, the first message of the lowest type that is less 
than or equal to the absolute value of msgtyp is received. 

msgflg specifies the action to be taken if a message of the desired type is not on 
the queue. These are as follows: 

If (msgflg &c IPCJIOWAIT) is "true", the calling process will return immedi- 
ately with a return value of -1 and errno set to ENOMSG. 

If (msgflg & IPC_N0WAIT) is "false", the calling process will suspend execu- 
tion until one of the following occurs: 

A message of the desired type is placed on the queue. 
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msqid is removed from the system. When this occurs, ermo is set 
equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. In this 
case a message is not received and the calling process resumes 
execution in the manner prescribed in signal(2). 

msgrcv will fail and no message will be received if one or more of the following 
are true: 

[EINVAL] mscfid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process. 

[EINVAL] msgsz is less than 0. 

[E2BIG] mtext is greater than msgsz and (msgflg & MSGJK)ERRC«) is "false". 

[ENOMSG] The queue does not contain a message of the desired type and 
(msgtyp & IPCNOWAIT) is "true". 

[EFAULT] ^sgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the 
data structure associated with mscjid [see intro(2)]. 

msg_qnum is decremented by 1. 

insg_lrpid is set equal to the process ID of the calling process. 
insg_rtime is set equal to the current time. 

SEE ALSO 

intro(2), insgctl(2), xnsgget(2), signal(2). 
DIAGNOSTICS 

If msgsnd or msgrcv return due to the receipt of a signal, a value of -1 is returned 
to the calling process and ermo is set to EINTR. If they return due to removal of 
msqid from the system, a value of -1 is returned and errno is set to EIDRM. 

Upon successful completion, the return value is as follows: 

msgsnd returns a value of 0. 

msgrcv returns a value equal to the number of bytes actually placed into 
mtext . 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

nice - change priority of a process 

SYNOPSIS 

int nice (incr) 
int incr; 

DESCRIPTION 

nice adds the value of incr to the nice value of the calling process. A process's 
nicevalue is a non-negative number for which a more positive value results in 
lower CPU priority. 

A maximum nice value of 39 and a minimimi nice value of 0 are imposed by the 
system. (The default nice value is 20.) Requests for values above or below these 
limits result in the nice value being set to the corresponding limit. 

[EPERM] nice will fail and not change the nice value if incr is negative or 

greater than 39 and the effective user ID of the calling process is 
not super-user. 

SEE ALSO 

exec(2). 

nice(l) in the User's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, nice returns the new nice value minus 20. Other- 
wise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

open - open for reading or writing 

SYNOPSIS 

finclude <fcntl.h> 

int open (path, oflag [, mode] ) 

char *path; 

int oflag, mode; 

DESCRIPTION 

path points to a path name naming a file, open opens a file descriptor for the 
named file and sets the file status flags according to the value of oflag. For non- 
STREAMS [see intro(2)] files, oflag values are constructed by or-ing flags from the 
following list (only one of the first three flags below may be used): 

0_RD0NLY Open for reading only. 

OJNRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

OJNDELAY This flag may affect subsequent reads and writes [see read(2) and 
write(2)]. 

When opening a FIFO with 0_RDONLY or 0_WRONLY set: 

If 0_NDELAY is set: 

An open for reading-only will return without delay. An 
open for writing-only will return an error if no process 
currently has the file open for reading. 

If 0_NDELAY is clear: 

An open for reading-only will block until a process opens 
the file for writing. An open for writing-only will block 
until a process opens the file for reading. 

When opening a file associated with a communication line: 

If 0__NDELAY is set: 

The open will return without waiting for carrier. 
If 0_NDELAY is clear: 

The open will block until carrier is present. 

0_APPEND If set, the file pointer will be set to the end of the file prior to each 
write. 

OJSYNC When opening a regular file, this flag affects subsequent writes. If 

set, each write(2) will wait for both the file data and file status to 
be physically updated. 

OjCREAT If the file exists, this flag has no effect. Otherwise, the owner ID 

of the file is set to the effective user ID of the process, the group 
ID of the file is set to the effective group ID of the process, and the 
low-order 12 bits of the file mode are set to the value of mode 
modified as follows [see creat(2)l: 
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All bits set in the file mode creation mask of the process 
are cleared [see i2inask(2)]. 

The "save text image after execution bit" of the mode is 
cleared [see chrood(2)]. 

0_TRUNC If the file exists, its length is truncated to 0 and the mode and 

owner are unchanged. 

0_EXCL If O EXCL and O CREAT are set, open will fail if the file exists. 

When opening a STREAMS file, oflag may be constructed from 0_NDELAY or-ed 
with either O RDONLY, 0__WRONLY or 0_^RDWR. Other flag values are not appli- 
cable to STREAMS devices and have no effect on them. The value of 0_NDELAY 
affects the operation of STREAMS drivers and certain system calls [see read(2), 
getinsg(2), putjnsg(2) and write(2)]. For drivers, the implementation of 
O NDELAY is device-specific. Each STREAMS device driver may treat this option 
differently. 

Certain flag values can be set following open as described in fcntl(2). 

The file pointer used to mark the current position within the file is set to the 
beginning of the file. 

The new file descriptor is set to remain open across exec system calls [see 
fcntl(2)]. 

The named file is opened unless one or more of the following are true: 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] oflag permission is denied for the named file. 

[EAGAIN] The file exists, mandatory file/record locking is set, and there are 

outstanding record locks on the file [see chitod (2)]. 

[EEXIST] O CREAT and O EXCL are set, and the named file exists. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the open system call. 

[EIO] A hangup or error occurred during a STREAMS open. 

[EISDIR] The named file is a directory and oflag is write or read /write. 

[EMFILE] NOFILES file descriptors are currently open. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

[ENFILE] The system file table is full. 

[ENOENT] 0_CREAT is not set and the named file does not exist. 

[ENOLINK] path points to a remote machine, and the link to that machine is 
no longer active. 

[ENOMEM] The system is imable to allocate a send descriptor. 
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[ENOSPC] 0_CREAT and 0_EXCL are set, and the file system is out of 

inodes. 

[ENOSR] Unable to allocate a stream. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] The named file is a character special or block special file, and the 

device associated with this special file does not exist. 

[ENXIO] 0_NDELAY is set, the named file is a FIFO, O^WRONLY is set, and 

no process has the file open for reading. 

[ENXIO] A STREAMS module or driver open routine failed. 

[EROFS] The named file resides on a read-only file system and oflag is 

write or read/write. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being exe- 
cuted and oflag is write or read /write. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), intro(2), lseelc(2), read(2), 
qetmsgil), putansg(2), uinaslc(2), write(2). 

DIAGNOSTICS 

Upon successful completion, the file descriptor is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

pause - suspend process until signal 

SYNOPSIS 

pause ( ) 

DESCRIPTION 

pause suspends the calling process until it receives a signal. The signal must be 
one that is not currently set to be ignored by the calling process. 

If the signal causes termination of the calling process, pause will not return. 

If the signal is caught by the calling process and control is returned from the 
signal-catching function [see signal(2)], the calling process resumes execution 
from the point of suspension; with a return value of -1 from pause and errno set 
to EINTR. 

SEE ALSO 

alanti(2), kill(2X signal(2), sigpause(2), wait(2). 
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NAME 

pipe - create an interprocess channel 

SYNOPSIS 

int pipe (fildes) 
int fildes [2]; 

DESCRIPTION 

pipe creates an I/O mechanism called a pipe and returns two file descriptors, 
fildeslO] and fildesll]. FildeslO] is opened for reading and fildesll] is opened for 
writing. 

Up to 5120 bytes of data are buffered by the pipe before the writing process is 
blocked. A read only file descriptor fildeslO] accesses the data written to fildes[l] 
on a first-in-first-out (FIFO) basis. 

pipe will fail if: 

[EMFILEl NOFILES file descriptors are currently open. 
[ENFILE] The system file table is full. 

SEE ALSO 

read(2), write(2). 

sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

plock - lock process, text, or data in memory 

SYNOPSIS 

♦include <sys/lock.h> 

int plock (op) 
int op; 

DESCRIPTION 

plock allows the calling process to lock its text segment (text lock), its data seg- 
ment (data lock), or both its text and data segments (process lock) into memory. 
Locked segments are immune to all routine swapping, plock also allows these 
segments to be unlocked. The effective user ID of the calling process must be 
super-user to use this call, op specifies the following: 

PROCLOCK - lock text and data segments into memory (process lock) 

TXTLCXac - lock text segment into memory (text lock) 

DATLCXX - lock data segment into memory (data lock) 

UNLOCK - remove locks 

plock will fail and not perform the requested operation if one or more of the fol- 
lowing are true: 

[EPERM] The effective user ID of the calling process is not super-user. 

[EINVAL] op is equal to PROCLOCK and a process lock, a text lock, or a data 

lock already exists on the calling process. 

[EINVAL] op is equal to TXTLOCK and a text lock, or a process lock already 

exists on the calling process. 

[EINVAL] op is equal to DATLCXac and a data lock, or a process lock already 

exists on the calling process. 

[EINVAL] op is equal to UNLOCK and no type of lock exists on the calling 

process. 

[EAGAIN] Not enough memory. 

SEE ALSO 

exec(2), exit(2), fork(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned to the calling process. Oth- 
erwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

poll - STREAMS input/output multiplexing 

SYNOPSIS 

♦include <stropts.h> 
♦include <poll.h> 

int polKfds, nfds, timeout) 
struct pollfd fds[]; 
unsigned long nfds; 
int timeout; 

DESCRIPTION 

poll provides users with a mechanism for multiplexing input/output over a set 
of file descriptors that reference open streams [see intro(2)]. poll identifies those 
streams on which a user can send or receive messages, or on which certain events 
have occurred. A user can receive messages using read(2) or getansg(2) and can 
send messages using write(2) and put:insg(2). Certain ioctl(2) calls, such as 
I RECVFD and I_SENDFD [see streainio(7)], can also be used to receive and send 
messages. 

fds specifies the file descriptors to be examined and the events of interest for each 
file descriptor. It is a pointer to an array with one element for each open file 
descriptor of interest. The arra5^s elements are pollfd structures which contain the 
following members: 

int fd; /* file descriptor */ 

short events; /* requested events */ 

short revents; /* returned events */ 

where fd specifies an open file descriptor and events and revents are bitmasks con- 
structed by or-ing any combination of the following event flags: 

POLLIN A non-priority or file descriptor passing message (see I RECVFD) is 
present on the stream head read queue. This flag is set even if the 
message is of zero length. In revents, this flag is mutually exclusive 
with POLLPRI. 

POLLPRI A priority message is present on the stream head read queue. This 
flag is set even if the message is of zero length. In revents, this flag 
is mutually exclusive with POLLIN. 

POLLOUT The first downstream write queue in the stream is not full. Priority 
control messages can be sent (see put^msg) at any time. 

POLLERR An error message has arrived at the stream head. This flag is only 
valid in the revents bitmask; it is not used in the events field. 

POLLHUP A hangup has occurred on the stream. This event and POLLOUT are 
mutually exclusive; a stream can never be writable if a hangup has 
occurred. However, this event and POLLIN or POLLPRI are not 
mutually exclusive. This flag is only valid in the revents bitmask; it 
is not used in the events field. 
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POLLNVAL The specified fd value does not belong to an open stream. This flag 
is only valid in the reoents field; it is not used in the events field. 

For each element of the array pointed to by fds, poll examines the given file 
descriptor for the event(s) specified in events. The number of file descriptors to be 
examined is specified by nfds. If nfds exceeds NOFILES, the system limit of open 
files [see ulimit(2)], poll will fail. 

If the value fd is less than zero, events is ignored and revents is set to 0 in that 
entry on return from poll. 

The results of the poll query are stored in the revents field in the pollfd structure. 
Bits are set in the revents bitmask to indicate which of the requested events are 
true. If none are true, none of the specified bits is set in revents when the poll 
call returns. The event flags POLLHUP, POLLERR and POLLNVAL are always set in 
revents if the conditions they indicate are true; this occurs even though these flags 
were not present in events. 

If none of the defined events have occurred on any selected file descriptor, poll 
waits at least timeout msec for an event to occur on any of the selected file 
descriptors. On a computer where millisecond timing accuracy is not available, 
timeout is rounded up to the nearest legal value available on that system. If the 
value timeout is 0, poll returns immediately. If the value of timeout is -1, poll 
blocks imtil a requested event occurs or until the call is interrupted, poll is not 
affected by the 0_NDELAY flag. 

poll fails if one or more of the following are true: 

[EAGAIN] Allocation of internal data structures failed but request should be 
attempted again. 

[EFAULT] Some argument points outside the allocated address space. 
[EINTR] A signal was caught during the poll system call. 

[EINVAL] The argument nfds is less than zero, or nfds is greater than NOFILES. 
SEE ALSO 

intro(2), read(2), getinsg(2), putinsg(2), write(2). 
streamio(7) in the System Administrator's Reference Manual. 
STREAMS Primer. 
STREAMS Programmer's Guide. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A positive value 
indicates the total number of file descriptors that has been selected (i.e., file 
descriptors for which the revents field is non-zero). A value of 0 indicates that the 
call timed out and no file descriptors have been selected. Upon failure, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

prof il - execution time profile 
SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 
char *buff ; 

int bufsiz, offset, scale; 
DESCRIPTION 

buff points to an area of core whose length (in bytes) is given by hufsiz. After this 
call, the user's program counter (pc) is examined each clock tick. Then the value 
of offset is subtracted from it, and the remainder multiplied by scale. If the result- 
ing number corresponds to an entry inside buff, that entry is incremented. An 
entry is defined as a series of bytes with length sizeof (short). 

The scale is interpreted as an unsigned, fixed-point fraction with binary point at 
the left: Oxffffffff (hex) gives a 1-1 mapping of pc's to words in buff; 0x7fffffff 
(hex) maps each pair of instruction words together. 02(octal) maps all instruc- 
tions onto the beginning of buff (producing a non-interrupting core clock). 

Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by giv- 
ing a bufsiz of 0. Profiling is turned off when an exec is executed, but remains 
on in child and parent both after a fork. Profiling will be turned off if an update 
in buff would cause a memory fault. 

SEE ALSO 

prof(l), tiines(2). 
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NAME 

ptrace - process trace 
SYNOPSIS 

int ptrace (request, pid, addr, data) 
int request, pid, addr, data; 

DESCRIPTION 

ptrace provides a means by which a parent process may control the execution of 
a child process. Its primary use is for the implementation of breakpoint debug- 
ging [see sdb(l)]. The child process behaves normally until it encounters a signal 
[see signal(2) for the list], at which time it enters a stopped state and its parent 
is notified via jvait(2). When the child is in the stopped state, its parent can 
examine and modify its "core image" using ptrace. Also, the parent can cause 
the child either to terminate or continue, with the possibility of ignoring the sig- 
nal that caused it to stop. 

The request argument determines the precise action to be taken by ptrace and is 
one of the following: 

0 This request must be issued by the child process if it is to be traced 
by its parent. It turns on the child's trace flag that stipulates that the 
cfiild should be left in a stopped state upon receipt of a signal rather 
than the state specified by func [see signal(2)]. The pid, addr, and 
data arguments are ignored, and a return value is not defined for this 
request. Peculiar results will ensue if the parent does not expect to 
trace the child. 

The remainder of the requests can only be used by the parent process. For each, 
pid is the process ID of the child. The child must be in a stopped state before 
these requests are made. 

1. 2 

With these requests, the word at location addr in the address space 
of the child is returned to the parent process. If I and D space are 
separated, request 1 returns a word from I space, and request 2 
returns a word from D space. If I and D space are not separated, 
either request 1 or request 2 may be used with equal results. The 
data argument is ignored. These two requests will fail if addr is not 
the start address of a word, in which case a value of - 1 is returned 
to the parent process and the parent's errno is set to EIO. 

3 With this request, the word at location addr in the child's USER area 
in the system's address space (see <sys/user . h>) is returned to the 
parent process. The data argument is ignored. This request will fail 
if addr is not the start address of a word or is outside the USER area, 
in which case a value of -1 is returned to the parent process and the 
parent's errno is set to EIO. 

4, 5 

With these requests, the value given by the data argument is written 
into the address space of the child at location addr. If I and D space 
are separated, request 4 writes a word into I space, and request 5 
writes a word into D space. If I and D space are not separated. 
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either request 4 or request 5 may be used with equal results. Upon 
successful completion, the value written into the address space of the 
child is returned to the parent. These two requests will fail if addr is 
not the start address of a word. Upon failure a value of -1 is 
returned to the parent process and the parent's ermo is set to EIO. 

6 With this request, a few entries in the child's USER area can be writ- 
ten, data gives the value that is to be written and addr is the location 
of the entry. The few entries that can be written are: 

the general registers 

the condition codes of the Processor Status Word. 

7 This request causes the child to resume execution. If the data argu- 
ment is 0, all pending signals including the one that caused the child 
to stop are canceled before it resumes execution. If the data argu- 
ment is a valid signal number, the child resumes execution as if it 
had incurred that signal, and any other pending signals are canceled. 
The addr argument must be equal to 1 for this request. Upon suc- 
cessful completion, the value of data is returned to the parent. This 
request will fail if data is not 0 or a valid signal number, in which 
case a value of -1 is returned to the parent process and the parent's 
errno is set to EIO. 

8 This request causes the child to terminate with the same conse- 
quences as exit(2). 

9 This request sets the trace bit in the Processor Status Word of the 
child and then executes the same steps as listed above for request 7. 
The trace bit causes an interrupt upon completion of one machine 
instruction. This effectively allows single stepping of the child. 

To forestall possible fraud, ptrace inhibits the set-user-id facility on subsequent 
execUD calls. If a traced process calls exec, it will stop before executing the first 
instruction of the new image showing signal SIGTRAP. ptrace will in general fail 
if one or more of the following are true: 

[EIO] request is an illegal number. 

[ESRCH] pid identifies a child that does not exist or has not executed a 

ptrace with request 0. 

SEE ALSO 

sdb(l), exec(2), signal(2), wait(2). 
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NAME 

putmsg - send a message on a stream 

SYNOPSIS 

♦include <stropts.h> 

int putmsg (£d, ctlptr, dataptr, flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int flags; 

DESCRIPTION 

putmsg creates a message [see intro(2)] from user specified buffer(s) and sends 
the message to a STREAMS file. The message may contain either a data part, a 
control part or both. The data and control parts to be sent are distinguished by 
placement in separate buffers, as described below. The semantics of each part is 
defined by the STREAMS module that receives the message. 

fd specifies a file descriptor referencing an open stream, ctlptr and dataptr each 
point to a strhuf structure which contains the following members: 

int maxlen; /* not used */ 

int len; /* length of data */ 

char *buf; /* ptr to buffer */ 

ctlptr points to the structure describing the control part, if any, to be included in 
the message. The huf field in the strhuf structure points to the buffer where the 
control information resides, and the len field indicates the number of bytes to be 
sent. The maxlen field is not used in putunsg [see get^nsg(2)]. In a similar 
manner, dataptr specifies the data, if any, to be included in the message, flags 
may be set to the values 0 or RS HIPRI and is used as described below. 

To send the data part of a message, dataptr must be non-NULL and the len field of 
dataptr must have a value of 0 or greater. To send the control part of a message, 
the corresponding values must be set for ctlptr. No data (control) part will be 
sent if either dataptr {ctlptr) is NULL or the len field of dataptr {ctlptr) is set to -1. 

If a control part is specified, and flags is set to RS_HIPRI, a priority message is sent. 
If flags is set to 0, a non-priority message is sent. If no control part is specified, 
and flags is set to RSJHIPRI, putmsg fails and sets ermo to EINVAL. If no control 
part and no data part are specified, and flags is set to 0, no message is sent, and 0 
is returned. 

For non-priority messages, putmsg will block if the stream write queue is full due 
to internal flow control conditions. For priority messages, putmsg does not block 
on this condition. For non-priority messages, putmsg does not block when the 
write queue is full and O NDELAY is set. Instead, it fails and sets errno to 
EAGAIN. 

putunsg also blocks, unless prevented by lack of internal resources, waiting for the 
availability of message blocks in the stream, regardless of priority or whether 
O NDELAY has been specified. No partial message is sent. 
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putmsg fails if one or more of the following are true: 

[EAGAIN] A non-priority message was specified, the O NDELAY flag is set 
and the stream write queue is full due to internal flow control con- 
ditions. 

[EBADF] fd is not a valid file descriptor open for writing. 

[EFAULT] ctlptr or dataptr points outside the allocated address space. 

[EINTR] A signal was caught during the putimsg system call. 

[EINVALl An undefined value was specified in flags, or flags is set to RS^HIPRI 
and no control part was supplied. 

[EINVAL] The stream referenced by fd is linked below a multiplexor. 

[ENOSR] Buffers could not be allocated for the message that was to be 
created due to insufficient STREAMS memory resources. 

[ENOSTR] A stream is not associated with fd. 

[ENXIO] A hangup condition was generated downstream for the specified 
stream. 

[ERANGE] The size of the data part of the message does not fall within the 
range specified by the maximum and minimum packet sizes of the 
topmost stream module. This value is also returned if the control 
part of the message is larger than the maximum configured size of 
the control part of a message, or if the data part of a message is 
larger than the maximum configured size of the data part of a mes- 
sage. 

A put:insg also fails if a STREAMS error message had been processed by the stream 
head before the call to putmsg. The error returned is the value contained in the 
STREAMS error message. 

SEE ALSO 

intro(2), read(2), getinsg(2), poll(2), write(2). 

STREAMS Primer. 

STREAMS Programmer's Guide. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

read - read from file 

SYNOPSIS 

int read (fildes, bu£, nbyte) 
int fildes; 
char *buf ; 
unsigned nbyte; 

DESCRIPTION 

fiJdes is a file descriptor obtained from a creat(2), open(2), di:?>(2), fcntl(2), or 
pipe(2) system call. 

read attempts to read nbyte bytes from the file associated with fildes into the 
buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given by 
the file pointer associated with fildes. Upon return from read, the file pointer is 
incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. The 
value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read and 
placed in the buffer; this number may be less than nbyte if the file is associated 
with a commimication line [see ioctl(2) and termio(7)], or if the number of 
bytes left in the file is less than nbyte bytes. A value of 0 is returned when an 
end-of-file has been reached. 

A read from a STREAMS [see intro(2)] file can operate in three different modes: 
"byte-stream" mode, "message-nondiscard" mode, and "message-discard" mode. 
The default is byte-stream mode. This can be changed using the I SRDOPT ioctl 
request [see streainio(7)], and can be tested with the I_GRDOPT ioctl. In byte- 
stream mode, read will retrieve data from the stream until it has retrieved nbyte 
bytes, or until there is no more data to be retrieved. Byte-stream mode ignores 
message boimdaries. 

In STREAMS message-nondiscard mode, read retrieves data until it has read nbyte 
bytes, or imtil it reaches a message boundary. If the read does not retrieve all 
the data in a message, the remaining data are replaced on the stream, and can be 
retrieved by the next read or getinsg(2) call. Message-discard mode also 
retrieves data until it has retrieved nbyte bytes, or it reaches a message boundary. 
However, unread data remaining in a message after the read returns are dis- 
carded, and are not available for a subsequent read or getmsg. 

When attempting to read from a regular file with mandatory file/record locking 
set [see chinod(2)], and there is a blocking (i.e. owned by another process) write 
lock on the segment of the file to be read: 

If O^^NDELAY is set, the read will return a -1 and set errno to EAG AIN. 

If O NDELAY is clear, the read will sleep until the blocking record lock is 
removed. 
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When attempting to read from an empty pipe (or FIFO): 
If O NDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data is written to the file or 
the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data currently 
available: 

If 0_NDELAY is set, the read will return a 0. 

If O^NDELAY is clear, the read will block until data becomes available. 

When attempting to read a file associated with a stream that has no data currently 
available: 

If O NDELAY is set, the read will return a -1 and set errno to EAG AIN. 

If O NDELAY is clear, the read will block until data becomes available. 

When reading from a STREAMS file, handling of zero-byte messages is determined 
by the current read mode setting. In byte-stream mode, read accepts data until it 
has read nhyte bytes, or until there is no more data to read, or until a zero-byte 
message block is encountered, read then returns the number of bytes read, and 
places the zero-byte message back on the stream to be retrieved by the next read 
or getmsg. In the two other modes, a zero-byte message returns a value of 0 and 
the message is removed from the stream. When a zero-byte message is read as 
the first message on a stream, a value of 0 is returned regardless of the read 
mode. 

A read from a STREAMS file can only process data messages. It cannot process 
any type of protocol message and will fail if a protocol message is encountered at 
the stream head, 

read will fail if one or more of the following are true: 

[EAGAIN] Mandatory file/record locking was set, O NDELAY was set, and 

there was a blocking record lock. 

[EAGAIN] Total amount of system memory available when reading via raw 

ID is temporarily insufficient. 

[EAGAIN] No message waiting to be read on a stream and O NDELAY flag 

set. 

[EBADF] fildes is not a valid file descriptor open for reading. 

[EBADMSG] Message waiting to be read on a stream is not a data message. 

[EDEADLK] The read was going to go to sleep and cause a deadlock situation 
to occur. 

[EFAULT] buf points outside the allocated address space. 

[EINTR] A signal was caught during the read system call. 

[EINVAL] Attempted to read from a stream linked to a multiplexor. 
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[ENOLCK] The system record lock table was full, so the read could not go 
to sleep until the blocking record lock was removed. 

[ENOLINK] fildes is on a remote machine and the link to that machine is no 
longer active. 

A read from a STREAMS file will also fail if an error message is received at the 
stream head. In this case, errno is set to the value returned in the error message. If 
a hangup occurs on the stream being read, read will continue to operate normally 
until the stream head read queue is empty. Thereafter, it will return 0. 

SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2),intro(2), open(2), pipe(2), getinscf(2). 
streaxnio(7), terxnio(7) in the System Administrator's Reference Manual 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating the 
number of bytes actually read. Otherwise, a -1 is returned and errno is set to 
indicate the error. 
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NAME 

rmdir - remove a directory 

SYNOPSIS 

int rmdir (path) 
char *path; 

DESCRIPTION 

rmdir removes the directory named by the path name pointed to by path. The 
directory must not have any entries other than "." and 

The named directory is removed xmless one or more of the following are true: 
[EINVAL] The current directory may not be removed. 

[EINVAL] The "." entry of a directory may not be removed. 

[EEXIST] The directory contains entries other than those for "." and 

[ENOTDIR] A component of the path prefbc is not a directory. 
[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the direc- 

tory to be removed. 

[EACCES] The parent directory has the sticky bit set and 

the parent directory is not owned by the user and 
the directory is not owned by the user and 
the directory is not writable by the user and 
the user is not superuser 

[EBUSY] The directory to be removed is the mount point for a mounted 

file system. 

[EROFS] The directory entry to be removed is part of a read-only file sys- 

tem. 

[EFAULT] path points outside the process's allocated address space. 

[EIO] An I/O error occurred while accessing the file system. 

[ENOLINK] path points to a remote machine, and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

mkdir(2). 

rmdir(l), rm(l), and mkdir(l) in the Use/s Reference Manual. 
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NAME 

seinctl - semaphore control operations 

SYNOPSIS 

tinclude <sys/types.h> 
tinclude <sys/ipc.h> 
♦include <sys/sem.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, and; 
int semnum; 
union semun { 
dLnt val; 

struct semidjds *bu£; 
ushort *array; 
} arg; 

DESCRIPTION 

semctl provides a variety of semaphore control operations as specified by and. 

The following cmds are executed with respect to the semaphore specified by semid 
and semnum: 

GETVMi Return the value of semval [see intro(2)]. {READ} 

SETVAL Set the value of semval to arg.val. {ALTER} When this cmd is 
successfully executed, the semadj value corresponding to the 
specified semaphore in all processes is cleared. 

GETPID Return the value of sempid. {READ} 

GETNCNT Return the value of semncnt. {READ} 

GETZCNT Return the value of semzcnt. {READ} 

The following cmds return and set, respectively, every semval in the set of sema- 
phores. 

GETALL Place semvals into array pointed to by argxirray. {READ} 

SETALL Set semvals according to the array pointed to by argxirray. 

{ALTER} When this cmd is successfully executed the semadj 
values corresponding to each specified semaphore in all 
processes are cleared. 

The following cmds are also available: 

IPC_STAT Place the current value of each member of the data structure 
associated with semid into the structure pointed to by arg.buf. 
The contents of this structure are defined in intro(2). {READ} 

IPC_SET Set the value of the following members of the data structure 
associated with semid to the corresponding value found in the 
structure pointed to by arg.buf: 
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senrperm.uid 
sem_perm.gid 

semjperm.niDde /* only low 9 bits */ 

This cmd can only be executed by a process that has an effec- 
tive user ID equal to either that of super-user, or to the value 
of semjperm.cuid or senij>ezm.uid in the data structure 
associated with semid. 

IPC_RMID Remove the semaphore identifier specified by semid from the 
system and destroy the set of semaphores and data structure 
associated with it. This cmd can only be executed by a pro- 
cess that has an effective user ID equal to either that of super- 
user, or to the value of semj>enn.cuid or semjperm.uid in 
the data structure associated with semid. 

semctl fails if one or more of the following are true: 

lEINVAL] semid is not a valid semaphore identifier. 

[EI^A^AL] semnum is less than zero or greater than semjisexns. 

[EINVALl cmd is not a valid command. 

[EACCES] Operation permission is denied to the calling process [see 

intro(2)]. 

[ERANGE] cmd is SETVAL or SETALL and the value to which semval is 
to be set is greater than the system imposed maximum. 

[EPERMl cmd is equal to IPC_RMID or IPCJSET and the effective user 

ID of the calling process is not equal to that of super-user, 
or to the value of semjperm.cuid or semjperm.uid in 
the data structure associated with semid. 

[EFAULT] arg.buf points to an illegal address. 

SEE ALSO 

intro(2), seroget(2), semDp(2). 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETPID The value of sempid. 

GETNCNT The value of semncnt. 

GETZCNT The value of semzcnt. 

All others A value of 0. 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

semget - get set of semaphores 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ipc.h> 
♦include <sys/sem.h> 

key_t key; 

int nsems, semflg; 

DESCRIPTION 

semget returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set containing nsems 
semaphores [see intro(2)] are created for key if one of the following is true: 

key is equal to IPC_PRIVATE. 

key does not already have a semaphore identifier associated with it, and 
isemflg & IPCJCREAT) is "true". 

Upon creation, the data structure associated with the new semaphore identifier is 
initialized as follows: 

sem^perm.cuid, sem_perm.uid, sem__penn.cgid, and sein_penn.gid are 
set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of sem_perm.mode are set equal to the low-order 9 
bits of semflg. 

senwisems is set equal to the value of nsems. 

semjotime is set equal to 0 and semjctime is set equal to the current 
time. 

semget fails if one or more of the following are true: 

[EINVAL] nsems is either less than or equal to zero or greater than the 

system-imposed limit. 

[EACCES] A semaphore identifier exists for key, but operation permission 

[see intro(2)] as specified by the low-order 9 bits of semflg 
would not be granted. 

[EINVAL] A semaphore identifier exists for key, but the number of sema- 

phores in the set associated with it is less than nsems, and nsems 
is not equal to zero. 

[ENOENT] A semaphore identifier does not exist for key and isemflg & 
IPC_CREAT) is "false". 

[ENOSPCl A semaphore identifier is to be created but the system-imposed 

limit on the maximum number of allowed semaphore identifiers 
system wide would be exceeded. 
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[ENOSPC] A semaphore identifier is to be created but the system-imposed 

limit on the maximum number of allowed semaphores system 
wide would be exceeded. 

[EEXIST] A semaphore identifier exists for key but ((semflg & IPC__C3^EAT) 

and isemflg & iPC_E30i)) is "true". 

SEE ALSO 

intro(2), semctl(2), seinop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a semaphore 
identifier, is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 
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NAME 

sexnop - semaphore operations 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ipc.h> 
♦include <sys/sem.h> 

int sexnop (sexnid, sops^ nsops) 
int sexnid; 

struct sexnbuf **sops; 
unsigned nsops; 

DESCRIPTION 

sexnop is used to automatically perform an array of semaphore operations on the 
set of semaphores associated with the semaphore identifier specified by semid. 
sops is a pointer to the array of semaphore-operation structures. Nsops is the 
number of such structures in the array. The contents of each structure includes 
the following members: 

short senwium; /* semaphore nuxrber ♦/ 
short sein_op; /* semaphore operation */ 
short sem__flg; /* operation flags */ 

Each semaphore operation specified by sem_op is performed on the corresponding 
semaphore specified by semui and semjium. 

sem op specifies one of three semaphore operations as follows: 

If sem_op is a negative integer, one of the following will occur: {ALTER} 

If semval [see intro(2)] is greater than or equal to the absolute 
value of sem_op, the absolute value of sem_op is subtracted from 
semval. Also, if {semjlg & semjundo) is "true", the absolute value 
of semj)p is added to the calling process's semadj value [see 
exit(2)] for the specified semaphore. 

If semval is less than the absolute value of semjyp and {semjlg & 
IPC_N0WAIT) is "true", semop will return immediately. 

If semval is less than the absolute value of semjjp and (semjlg & 
IPCJIOWAIT) is "false", sexnop will increment the semncnt associ- 
ated with the specified semaphore and suspend execution of the 
calling process until one of the following conditions occur. 

semval becomes greater than or equal to the absolute value of 
sem_op. When this occurs, the value of semncnt associated with 
the specified semaphore is decremented, the absolute value of 
semj)p is subtracted from semval and, if (semjlg & SEMJJNDO) is 
"true", the absolute value of semyp is added to the calling 
process's semadj value for the specified semaphore. 

The semid for which the calling process is awaiting action is 
removed from the system [see sexnctl(2)]. When this occurs, 
errno is set equal to EIDRM, and a value of - 1 is returned. 
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The calling process receives a signal that is to be caught. When 
this occurs, the value of semncnt associated with the specified 
semaphore is decremented, and the calling process resumes exe- 
cution in the manner prescribed in signal(2). 

If semj)p is a positive integer, the value of semjop is added to semval 
and, if (semjlg & sem_undo) is "true", the value of semjyp is subtracted 
from the calling process's semadj value for the specified semaphore. 
{ALTER} 

If sem_op is zero, one of the following will occur: {READ} 

If semval is zero, semop will return immediately. 

If semval is not equal to zero and (semjlg & IPCJIOWAIT) is 
"true", semop will return immediately. 

If semval is not equal to zero and (sem Jig & IPC_N0WAIT) is 
"false", sexnop will increment the semzcnt associated with the 
specified semaphore and suspend execution of the calling process 
until one of the following occurs: 

semval becomes zero, at which time the value of semzcnt associ- 
ated with the specified semaphore is decremented. 

The semid for which the calling process is awaiting action is 
removed from the system. When this occurs, errno is set equal 
to EIDRM, and a value of - 1 is returned. 

The calling process receives a signal that is to be caught. When 
this occurs, the value of semzcnt associated with the specified 
semaphore is decremented, and the calling process resumes exe- 
cution in the manner prescribed in signal(2). 

semop will fail if one or more of the following are true for any of the semaphore 
operations specified by sops: 

[EINVAL] semid is not a valid semaphore identifier. 

[EFBIG] semjium is less than zero or greater than or equal to the nimiber 

of semaphores in the set associated with semid, 

[E2BIG] nsops is greater than the system-imposed maximum. 

[EACCES] Operation permission is denied to the calling process [see 

intro(2)] 

[EAGAIN] The operation would result in suspension of the calling process 

but (semjlg & ipcjjowait) is "true". 

[ENOSPCl The limit on the number of individual processes requesting an 
SEMJUNDO would be exceeded. 

[EINVAL] The number of individual semaphores for which the calling pro- 

cess requests a SEMJUNDO would exceed the limit. 
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[ERANGE] An operation would cause a semval to overflow the system- 
imposed limit. 

[ERANGE] An operation would cause a semadj value to overflow the 

system-imposed limit. 

[EFAULT] sops points to an illegal address. 

Upon successful completion, the value of sempid for each semaphore specified in 
the array pointed to by sops is set equal to the process ID of the calling process. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), seroctl(2), seiwget(2). 
DIAGNOSTICS 

If semop returns due to the receipt of a signal, a value of -1 is returned to the cal- 
ling process and errno is set to EINTR. If it returns due to the removal of a semid 
from the system, a value of -1 is returned and errno is set to EIDRM. 

Upon successful completion, a value of zero is returned. Otherwise, a value of -1 
is returned and errno is set to indicate the error. 
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NAME 

setpgrp - set process group ID 

SYNOPSIS 

int setpgzp ( ) 

DESCRIPTION 

setpgrp sets the process group ID of the calling process to the process ID of the 
calling process and returns the new process group ID. 

SEE ALSO 

exec(2), f ork(2), getpid(2), intro(2), kill(2), signal(2). 
DIAGNOSTICS 

setpgrp returns the value of the new process group ID. 
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NAME 

setuid, setgid - set user and group IDs 

SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

setuid (setgid) is used to set the real user (group) ID and effective user (group) 
ID of the calling process. 

If the effective user ID of the calling process is super-user, the real user (group) ID 
and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real user 
(group) ID is equal to uid (gid), the effective user (group) ID is set to uid (gid). 

If the effective user ID of the calling process is not super-user, but the saved set- 
user (group) ID from exec(2) is equal to uid (gid), the effective user (group) ID is 
set to uid (g;id). 

setuid (setgid) will fail if the real user (group) ID of the calling process is not 
equal to uid (gid) and its effective user ID is not super-user. [EPERM] 

The uid is out of range. lEINVAL] 

SEE ALSO 

getuid(2), intro(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

shmctl - shared memory control operations 

SYNOPSIS 

♦include <sys /types . h> 
♦include <sys/ipc.h> 
♦include <sys/shm.h> 

int shmctl (shmid, cind, buf) 
int shmid, and; 
struct shmidjds *buf ; 

DESCRIPTION 

shmctl provides a variety of shared memory control operations as specified by 
and. The following cmds are available: 

IPC__STAT Place the current value of each member of the data structure associ- 
ated with shmid into the structure pointed to by buf. The contents of 
this structure are defined in intro(2). {READ} 

IPC_SET Set the value of the following members of the data structure associ- 
ated with shmid to the corresponding value found in the structure 
pointed to by huf: 

shm_peiin.uid 
shmjperm.gid 

shm_perm.mDde /* only low 9 bits */ 

This and can only be executed by a process that has an effective user 
ID equal to that of super user, or to the value of shm_perm. cuid or 
shm_perm.uid in the data structure associated with shmid. 

IPCJ<MID Remove the shared memory identifier specified by shmid from the 
system and destroy the shared memory segment and data structure 
associated with it. This and can only be executed by a process that 
has an effective user ID equal to that of super user, or to the value of 
shm_perm.cuid or shm__perm.uid in the data structure associated 
with shmid. 

SHM_LOCK Lock the shared memory segment specified by shmid in memory. 

This and can only be executed by a process that has an effective user 
ID equal to super user. 

SHM_UNLOCK Unlock the shared memory segment specified by shmid. This and 
can only be executed by a process that has an effective user ID equal 
to super user. 

shmctl will fail if one or more of the following are true: 
[EINVAL] shmid is not a valid shared memory identifier. 
[EINVAL] and is not a valid command. 

[EACCESl and is equal to IPCJSTAT and {READ} operation permission is denied 
to the calling process [see intro(2)]. 
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[EPERM] 



and is equal to ipc_rmid or IPCJSET and the effective user ID of the 
calling process is not equal to that of super user, or to the value of 
shnrperm.cuid or shmj>enn.uid in the data structure associated 
with shmid. 



[EPERM] and is equal to SHM_LOCK or SHM_UNL0CK and the effective user ID of 
the calling process is not equal to that of super user. 

[EFAULT] buf points to an illegal address. 

[ENOMEM] and is equal to SHM_LOac and there is not enough memory. 

SEE ALSO 

shmgiet(2), shxtiop(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 



The user must explicitly remove shared memory segments after the last reference 
to them has been removed. 



NOTES 
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NAME 

shmget - get shared memory segment identifier 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ipc.h> 
♦include <sys/shm.h> 

keyjt key; 

int size, shmflg; 

DESCRIPTION 

shmget returns the shared memory identifier associated with key. 

A shared memory identifier and associated data structure and shared memory 
segment of at least size bytes [see intro(2)] are created for key if one of the fol- 
lowing are true: 

key is equal to ipc_privme. 

key does not already have a shared memory identifier associated with it, 
and (shmflg & ipcjCREAT) is "true". 

Upon creation, the data structure associated with the new shared memory 
identifier is initialized as follows: 

shmj)erm.cuid, shm_perm.uid, shmjperm.cgid, and shmj)erm.gid are 
set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of shinj>erm.mcxie are set equal to the low-order 9 
bits of shmflg. shm_segsz is set equal to the value of size. 

shxn_lpid, shxn_nattch shm_atiine, and shmjdtime are set equal to 0. 

shmjctime is set equal to the current time. 

shmget will fail if one or more of the following are true: 

[EINVAL] size is less than the system-imposed minimum or greater than the 

system-imposed maximum. 

[EACCES] A shared memory identifier exists for key but operation permis- 

sion [see intro(2)] as specified by the low-order 9 bits of shmflg 
would not be granted. 

[EINVAL] A shared memory identifier exists for key but the size of the seg- 

ment associated with it is less than size and size is not equal to 
zero. 

[ENOENT] A shared memory identifier does not exist for key and (shmflg & 

ipc_creat) is "false". 

[ENOSPC] A shared memory identifier is to be created but the system- 

imposed limit on the maximum number of allowed shared 
memory identifiers system wide would be exceeded. 
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[ENOMEM] 



A shared memory identifier and associated shared memory seg- 
ment are to be created but the amount of available memory is 
not sufficient to fill the request. 



[EEXIST] 



A shared memory identifier exists for key but ((shtnflg & 
IPC_CREAT) and (shmjig&c IPCJBXCL)) is "true". 



SEE ALSO 

intro(2), shmctl(2), shinpp(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a shared memory 
identifier is returned. Otherwise, a value of -1 is returned and ermo is set to 
indicate the error. 



The user must explicitly remove shared memory segments after the last reference 
to them has been removed. 



NOTES 
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NAME 

shroop - shared memory operations 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/ipc.h> 
♦include <sys/shm.h> 

char '•'shmat (shmid, shxnaddr, shmflg) 
int shmid; 
char *shxnaddr; 
int shmflg; 

int shmdt (shmaddr) 
char * shmaddr; 

DESCRIPTION 

shmat attaches the shared memory segment associated with the shared memory 
identifier specified by shmid to the data segment of the calling process. The seg- 
ment is attached at the address specified by one of the following criteria: 

If shmaddr is equal to zero, the segment is attached at the first available 
address as selected by the system. 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is "true", the seg- 
ment is attached at the address given by (shmaddr - (shmaddr modulus 
Shmlba)). 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is "false", the seg- 
ment is attached at the address given by shmaddr. 

shmdt detaches from the calling process's data segment the shared memory seg- 
ment located at the address specified by shmaddr. 

The segment is attached for reading if (shmflg & SHM__RDONLY) is "true" {READ}, 
otherwise it is attached for reading and writing {READ/WRITE}. 

shmat will fail and not attach the shared memory segment if one or more of the 
following are true: 

[EINVAL] shmid is not a valid shared memory identifier. 

[EACCES] Operation permission is denied to the calling process [see 

intro(2)]. 

[ENOMEM] The available data space is not large enough to accommodate the 
shared memory segment. 

[EINVAL] shmaddr is not equal to zero, and the value of (shmaddr - 

(shmaddr modulus SHMIBA)) is an illegal address. 

[EINVAL] shmaddr is not equal to zero, (shmflg & shm__RND) is "false", and 

the value of shmaddr is an illegal address. 

[EMFILE] The ntimber of shared memory segments attached to the calling 

process would exceed the system-imposed limit. 
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[EINVAL] 



shmdt will fail and not detach the shared memory segment if 
shmaddr is not the data segment start address of a shared 
memory segment. 



SEE ALSO 



exec(2), exit(2), fork(2X intro(2), shmctl(2), shniget(2). 



DIAGNOSTICS 



Upon successful completion, the return value is as follows: 

skmat returns the data segment start address of the attached shared 
memory segment. 

shmdt returns a value of 0. 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 



The user must explicitly remove shared memory segments after the last reference 
to them has been removed. 



NOTES 



Page 2 



10/89 



signal (2) 



signal (2) 



NAME 

signal - specify what to do upon receipt of a signal 

SYNOPSIS 

tinclude <signal.h> 

void (* signal (sig, func) ) ( ) 

int sig; 

void (♦func) ( ) ; 

DESCRIPTION 

signal allows the calling process to choose one of three ways in which it is pos- 
sible to handle the receipt of a specific signal, sig specifies the signal and func 
specifies the choice. 

sig can be assigned any one of the following except SIGKILL: 



SIGHUP 

SIGINT 

SIGQUIT 

SI6ILL 

SIGTRAP 

SIGIOT 

SIGEMT 

SIGFPE 

SIGKILL 

SIGBUS 

SIGSEGV 

SIGSYS 

SIGPIPE 

SIGALRM 

SIGTERM 

SIGUSRl 

SIGUSR2 

SIGCLD 

SIGPWR 

SIGPOLL 



01 
02 

03" 

04"- 

05" 

06" 

07" 

08" 

09 

10" 

11" 

12" 

13 

14 

15 

16 

17 

18^21 

19[2] 

22^3] 



hangup 

interrupt 

quit 

illegal instruction (not reset when caught) 

trace trap (not reset when caught) 

lOT instruction 

EMT instruction 

floating point exception 

kill (cannot be caught or ignored) 

bus error 

segmentation violation 

bad argument to system call 

write on a pipe with no one to read it 

alarm clock 

software termination signal 
user-defined signal 1 
user-defined sienal 2 
death of a chila 
power fail 

selectable event pending 



func is assigned one of three values: SlGj)Plv SIG_IGM, or a function address. 
SIG^DFL, and SIG_IGM, are defined in the include file signaLh. Each is a macro that 
expands to a constant expression of type pointer to function returning void, and 
has a unique value that matches no declarable function. 

The actions prescribed by the values of func are as follows: 

SIGJ)FL - terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be terminated 
with all of the consequences outlined in exit(2). See NOTE [11 below. 

SIG_IGN - ignore signal 

The signal sig is to be ignored. 
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Note: the signal SIGKILL cannot be ignored. 

function address - catch signal 

Upon receipt of the signal sig, the receiving process is to execute the 
signal-catching function pointed to by func. The signal number sig 
will be passed as the only argument to the signal-catching function. 
Additional arguments are passed to the signal-catching function for 
hardware-generated signals. Before entering the signal-catching func- 
tion, the value of func for the caught signal will be set to SIGJDFL 
unless the signal is siGlLlv SIGTRAP, or SIGPWR. 

Upon return from the signal-catching function, the receiving process 
will resume execution at the point it was interrupted. 

When a signal that is to be caught occurs during a read(2), a write(2), 
an ppen(2), or an ioctl(2) system call on a slow device (like a termi- 
nal; but not a file), during a pause(2) system call, or during a wait(2) 
system call that does not return immediately due to the existence of a 
previously stopped or zombie process, the signal catching function will 
be executed and then the interrupted system call may return a -1 to 
the calling process with errno set to EINTR. 

signal will not catch an invalid function argument, func, and results 
are undefined when an attempt is made to execute the function at the 
bad address. 

Note: The signal SIGKILL cannot be caught. 
A call to signal cancels a pending signal sig except for a pending SIGKILL signal, 
signal will fail if sig is an illegal signal number, including SIGKILL. [EINVAL] 

NOTES 

[1] 

If SIGJ)FL is assigned for these signals, in addition to the process being ter- 
minated, a "core image" will be constructed in the current working directory 
of the process, if the following conditions are met: 

The effective user ID and the real user ID of the receiving process are 
equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following pro- 
perties: 

a mode of 0666 modified by the file creation mask [see 
umasUl)] 

a file owner ID that is the same as the effective user ID of 
the receiving process. 

a file group ID that is the same as the effective group ID of 
the receiving process 

[2] 

For the signals SIQCLD and SIGPWE^ func is assigned one of three values: 
SIG_DFL, SIG__IGN, or a function address. The actions prescribed by these values 
are: 
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SIG_DFL - ignore signal 

The signal is to be ignored. 

SIG_IGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling 
process's child processes will not create zombie processes when 
they terminate [see exit (2)]. 

function address - catch signal 

If the signal is SIGPWR^ the action to be taken is the same as that 
described above for func equal to function address. The same is 
true if the signal is SIGCLD with one exception: while the process 
is executing the signal-catching fimction, any received SIGCID sig- 
nals will be ignored. (This is the default action.) 

In addition, SIGCLD affects the wait, and exit system calls as follows: 

wait If the func value of SIGCLD is set to SIG_IGN and a wait is exe- 
cuted, the wait will block until all of the calling process's child 
processes terminate; it will then return a value of - 1 with errno set 
to ECHILD. 

exit If in the exiting process's parent process the func value of siqcld 
is set to SIG_IGM, the exiting process will not create a zombie pro- 
cess. 

When processing a pipeline, the shell makes the last process in the pipeline 
the parent of the proceeding processes. A process that may be piped into 
in this manner (and thus become the parent of other processes) should take 
care not to set SIGCLD to be caught. 

[3] 

SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see 
intro(2)] file has a "selectable" event pending. A process must specifically 
request that this signal be sent using the I_SETSIG ioctl call. Otherwise, the 
process will never receive SIGPOLL. 

SEE ALSO 

intro(2), kill(2), pause(2), ptrace(2), wait(2), set jnp(3C), sigset(2). 
kill(l) in the Use/s Reference Manual. 

DIAGNOSTICS 

Upon successful completion, signal returns the previous value of func for the 
specified signal sig. Otherwise, a value of SIG_ERR is returned and ermo is set to 
indicate the error. SIG_ERR is defined in the include file signal.h. 
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NAME 

sigset, sighold, sigrelse, sigignore^ sigpause ~ signal management 

SYNOPSIS 

tinclude <signal.h> 

void ('Csigset (sig, func) ) ( ) 

int sig; 

void (*func) ( ) ; 

int sighold (sig) 

int sig; 

int sigrelse (sig) 

int sig; 

int sigignore (sig) 

int sig; 

int sigpause (sig) 

int sig; 

DESCRIPTION 

These functions provide signal management for application processes, sigset 
specifies the system signal action to be taken upon receipt of signal sig. This 
action is either calling a process signal-catching handler func or performing a 
system-defined action. 

sig can be assigned any one of the following values except SIGKILL. Machine or 
implementation dependent signals are not included (see NOTES below). Each 
value of sig is a macro, defined in <signal.h>, that expands to an integer con- 
stant expression. 

SIGEKJP hangup 

SIGINT interrupt 

SIGQUIT* quit 

SIGILL* illegal instruction (not held when caught) 

SIGTRAP* trace trap (not held when caught) 

SIGABRT* abort 

SIGFPE* floating point exception 

SIGKILL kill (can not be caught or ignored) 

SIGSYS* bad argument to system call 

SIGPIPE write on a pipe with no one to read it 

siGAii^ alarm clock 

SIGTERM software termination signal 

SIGUSRI user-defined signal 1 

SIGUSR2 user-defined signal 2 

SIGCLD death of a child (see NOTES below) 

SIGPWR power fail (see NOTES below) 

SIGPOLL selectable event pending (see NOTES below) 

See below imder SIG DFL regarding asterisks (*) in the above list. 
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The following values for the system-defined actions of func are also defined in 
<signal.h>. Each is a macro that expands to a constant expression of type 
pointer to fimction returning void and has a unique value that matches no declar- 
able function. 

SIGJ)FL - default system action 

Upon receipt of the signal sig, the receiving process is to be terminated 
with all of the consequences outlined in exit (2). In addition a "core 
image" will be made in the current working directory of the receiving 
process if sig is one for which an asterisk appears in the above list and 
the following conditions are met: 

The effective user ID and the real user ID of the receiving pro- 
cess are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following 
properties: 

a mode of 0666 modified by the file creation mask 
[see umaskd)] 

a file owner ID that is the same as the effective user 
ID of the receiving process. 

a file group ID that is the same as the effective group 
ID of the receiving process 

SIG_IGN - ignore signal 

Any pending signal sig is discarded and the system signal action is set to 
ignore future occurrences of this signal type. 

SIG_H0ID - hold signal 

The signal sig is to be held upon receipt. Any pending signal of this 
type remains held. Only one signal of each type is held. 

Otherwise, func must be a pointer to a function, the signal-catching handler, that 
is to be called when signal sig occurs. In this case, sigset specifies that the pro- 
cess will call this function upon receipt of signal sig. Any pending signal of this 
type is released. This handler address is retained across calls to the other signal 
management functions listed here. 

When a signal occurs, the signal number sig will be passed as the only argument 
to the signal-catching handler. Before calling the signal-catching handler, the sys- 
tem signal action will be set to SIG_HOLD . During normal return from the 
signal-catching handler, the system signal action is restored to func and any held 
signal of this type released. If a non-local goto (longjmp) is taken, then sigrelse 
must be called to restore the system signal action and release any held signal of 
this type. 

In general, upon return from the signal-catching handler, the receiving process 
will resume execution at the point it was interrupted. However, when a signal is 
caught during a read(2), a write(2), an open(2), or an ioctl(2) system call dur- 
ing a sigpause system call, or during a wait(2) system call that does not return 
immediately due to the existence of a previously stopped or zombie process, the 
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signal-catching handler will be executed and then the interrupted system call may 
return a -1 to the calling process with ermo set to EINTR. 

sighold and sigrelse are used to establish critical regions of code, sighold is 
analogous to raising the priority level and deferring or holding a signal until the 
priority is lowered by sigrelse. sigrelse restores the system signal action to 
that specified previously by sigset. 

sigignore sets the action for signal sig to SIG JGN (see above). 

sigpause suspends the calling process until it receives a signal, the same as 
pause(2). However, if the signal sig had been received and held, it is released 
and the system signal action taken. This system call is useful for testing variables 
that are changed on the occurrence of a signal. The correct usage is to use sig- 
hold to block the signal first, then test the variables. If they have not changed, 
then call sigpause to wait for the signal, sigset will fail if one or more of the 
following are true: 

[EINVAL] sig is an illegal signal number (including SIGKILL) or the default 

handling of sig cannot be changed. 

[EINTR] A signal was caught during the system call sigpause. 

DIAGNOSTICS 

Upon successful completion, sigset returns the previous value of the system sig- 
nal action for the specified signal sig. Otherwise, a value of SIG ERR is returned 
and errno is set to indicate the error. SIG__ERR is defined in <signal.h>. 

For the other functions, upon successful completion, a value of 0 is returned. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 

SEE ALSO 

kill(2), pause(2), signal(2), wait(2), set jirp(3C). 

NOTES 

Two signals that behave differently than the signals described above exist in this 
release of the system: 

SIQCU) death of a child (reset when caught) 
SIGPWR power fail (not reset when caught) 

For these signals, func is assigned one of three values: SIG^DFL, SIG JGN, or a 
function address. The actions prescribed by these values are as follows: 

SIGJ)FL - ignore signal 

The signal is to be ignored. 

SIG_IGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCU), the calling process's 
child processes will not create zombie processes when they terminate 
[see exit (2)]. 

function address - catch signal 

If the signal is siGPWR, the action to be taken is the same as that 
described above for func equal to function address. The same is true if 
the signal is SIGCLD with one exception: while the process is executing 
the signal-catching function, any received SIGCLD signals will be 
ignored. (This is the default action.) 
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The SIGCLD affects two other system calls [xvaitd), and exit (2)] in the following 
ways: 

wait If the func value of siGCLD is set to SIGJGN and a wait is executed, the 
wait will block until all of the calling process's child processes ter- 
minate; it will then return a value of -1 with ermo set to ECHILD. 

exit If in the exiting process's parent process the func value of siGCii) is set 
to SIGJGN , the exiting process will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the pipeline the 
parent of the proceeding processes. A process that may be piped into in this 
manner (and thus become the parent of other processes) should take care not to 
set SIGCLD to be caught. 

SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see 
intro(2)] file has a "selectable" event pending. A process must specifically 
request that this signal be sent using the I_SETSIG ioctl(2) call [see 
streainio(7)]. Otherwise, the process will never receive SIGPOLL. 

For portability, applications should use only the symbolic names of signals 
rather than their values and use only the set of signals defined here. The action 
for the signal SIGKILL can not be changed from the default system action. 

Specific implementations may have other implementation-defined signals. Also, 
additional implementation-defined arguments may be passed to the signal- 
catching handler for hardware-generated signals. For certain hardware- 
generated signals, it may not be possible to resume execution at the point of 
interruption. 

The signal type SIGSEGV is reserved for the condition that occurs on an invalid 
access to a data object. If an implementation can detect this condition, this sig- 
nal type should be used. 

The other signal management functions, signal(2) and pause(2), should not be 
used in conjunction with these routines for a partictdar signal type. 
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NAME 

Stat, f Stat - get file status 

SYNOPSIS 

tinclude <sys/types . h> 
♦include <sys/stat.h> 

int Stat (path, buf ) 
char *path; 
Struct Stat *buf ; 

int fstat (fildes, buf) 
int fildes; 
struct Stat *buf ; 

DESCRIPTION 

path points to a path name naming a file. Read, write, or execute permission of 
the named file is not required, but all directories listed in the path name leading 
to the file must be searchable, stat obtains information about the named file. 

Note that in a Remote File Sharing environment, the information returned by 
Stat depends upon the user /group mapping set up between the local and 
remote computers. [See idload(lM)]. 

fstat obtains information about an open file known by the file descriptor fildes, 
obtained ft-om a successful open, creat, dup, f cntl, or pipe system call. 

buf is a pointer to a stat structure into which information is placed concerning 
the file. 

The contents of the structure pointed to by buf include the following members: 



ushort 


st_jnode; 


/* 


ino_t 


st__ino; 


/* 


devj; 


st__dev; 


/* 






/* 


devj: 


st_j:dev; 


/* 






/* 






/* 


short 


st_nlink; 


/* 


ushort 


stjuid; 


/* 


ushort 


st_gid; 


/* 


off_t 


st__size; 


/* 


timejt 


st_atiine; 


/* 


timejt 


st^jntiine; 


/* 


timejt 


st_ctime; 


/* 






/* 






/* 



st_inode The mode of the file as descril^ed in the inknod(2) system call. 

st_ino This field uniquely identifies the file in a given file system. The pair 
st ino and st_dev uniquely identifies regular files. 
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st_dev This field uniquely identifies the file system that contains the file. Its 
value may be used as input to the ustat(2) system call to determine 
more information about this file system. No other meaning is associ- 
ated with this value. 

st__rdev This field should be used only by administrative commands. It is 
valid only for block special or character special files and only has 
meaning on the system where the file was configured. 

st_nlink This field should be used only by administrative commands. 

stjuid The user ID of the file's owner. 

st_gid The group ID of the file's group. 

st_size For regular files, this is the address of the end of the file. For pipes or 
fifos, this is the count of the data currently in the file. For block spe- 
cial or character special, this is not defined. 

st_atiine Time when file data was last accessed. Changed by the following sys- 
tem calls: creat(2), xnknod(2), pipe(2), utiine(2), and read(2). 

st_intixne Time when data was last modified. Changed by the following system 
calls: Great (2), inknod(2), pipe(2), utime(2), and write(2). 

st__ctime Time when file status was last changed. Changed by the following 
system calls: chinod(2), chown(2), creat(2), link(2), inknod(2), pipe(2), 
unlink(2), utiroe(2), and write(2). 

Stat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] buf or path points to an invalid address. 

[EINTR] A signal was caught during the stat system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

f Stat will fail if one or more of the following are true: 
[EBADF] fildes is not a valid open file descriptor. 

[EFAULT] huf points to an invalid address. 

[ENOLINK] fildes points to a remote machine and the link to that machine is 
no longer active. 

SEE ALSO 

chniod(2), chown(2), creat(2), link(2), roknod(2), pipe(2), read(2), tiine(2), 
unlink(2), utime(2), write(2). 
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DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

statf s, f statf s - get file system inforaiation 

SYNOPSIS 

# include <sys/ types. h> 
tinclude <sys/stat£s.h> 

int statfs (path, bu£, len, fstyp) 

char ♦path; 

struct statfs *buf ; 

int len, fstyp; 

int fstatfs (fildes, buf, len, fstyp) 

int fildes; 

struct statfs *buf ; 

int len, fstyp; 

DESCRIPTION 

statfs returns a "generic superblock" describing a file system. It can be used to 
acquire information about mounted as well as unmoimted file systems, and usage 
is slightly different in the two cases. In all cases, buf is a pointer to a structure 
(described below) which will be filled by the system call, and len is the number of 
bytes of information which the system should return in the structure, len must 
be no greater than sizeof (struct statfs) and ordinarily it will contain 
exactly that value; if it holds a smaller value the system will fill the structure with 
that number of bytes. (This allows future versions of the system to grow the 
structure without invalidating older binary programs.) 

If the file system of interest is currently mounted, path should name a file which 
resides on that file system. In this case the file system type is known to the 
operating system and the fstyp argument must be zero. For an unmoimted file 
system path must name the block special file containing it and fstyp must con- 
tain the (non-zero) file system type. In both cases read, write, or execute permis- 
sion of the named file is not required, but all directories listed in the path name 
leading to the file must be searchable. 

The statfs structure pointed to by buf includes the following members: 
short f__fstyp; /* File system type */ 
short fjDsize; /* Block size */ 
short f_frsize; /* Fragment size */ 
long fjblocks; /♦ Total nuirber of blocks */ 
long f jDfree; /* Count of free blocks */ 
long f_files; /* Total number of file nodes */ 
long f_ffree; /* Count of free file nodes */ 
char f__fname[6] ;/* Volume name */ 
char f_fpackt6];/* Pack name */ 

fstatfs is similar, except that the file named by path in statfs is instead 
identified by an open file descriptor fikdes obtained from a successful open(2), 
creat(2), dup(2), fcntl(2), or pipe(2) system call. 
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statf s obsoletes ustat(2) and should be used in preference to it in new pro- 
grams. 

statf s and f statf s will fail if one or more of the following are true: 
[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] buf or path points to an invalid address. 

[EBADFl fildes is not a valid open file descriptor. 

[EINVAL] fstyp is an invalid file system type; path is not a block special file 

and fstyp is nonzero; len is negative or is greater than sizeof 
(struct statf s). 

[ENOLINK] path points to a remote machine, and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

chinod(2), chown(2), creat(2), link(2), inknod(2), pipe(2), read(2), tiine(2), 
unlink(2), utime(2), write(2), f s(4). 
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NAME 

stiine - set time 

SYNOPSIS 

int stime (tp) 
long *tp; 

DESCRIPTION 

stiine sets the system's idea of the time and date, tp points to the value of time 
as measured in seconds from 00:00:00 GMT January 1, 1970. 

[EPERM] stiine will fail if the effective user ID of the calling process is not 

super-user. 

SEE ALSO 

tiine(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

sync - update super block 

SYNOPSIS 

void sync ( ) 

DESCRIPTION 

sync causes all information in memory that should be on disk to be written out. 
This includes modified super blocks, modified i-nodes, and delayed block I/O. 

It should be used by programs which examine a file system, for example f sck, 
df , etc. It is mandatory before a re-boot. 

The writing, although scheduled, is not necessarily complete upon return from 
sync. 
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NAME 

sysf s - get file system type information 

SYNOPSIS 

♦include <sys/fstyp.h> 
♦include <sys/fsid.h> 

int sysfs (opcode, fsnaine) 
int opcode; 
char * fsnaine; 

int sysfs (opcode, fs_index, buf) 
int opcode; 
int fs_index; 
char *buf ; 

int sysfs (opcode) 
int opcode; 

DESCRIPTION 

sysfs returns information about the file system types configured in the system. 
The number of arguments accepted by sysfs varies and depends on the opcode. 
The currently recognized opcodes and their functions are described below: 

GETFSIND translates fsname, a null-terminated file-system 

identifier, into a file-system type index. 

GETFSTYP translates fsjndex, a file-system type index, into a null- 

terminated file-system identifier and writes it into the 
buffer pointed to by huf) this buffer must be at least of 
size FSTYPSZ as defined in <sys/fstyp.h>. 

GETNFSTYP returns the total number of file system types 

configured in the system. 

sysfs will fail if one or more of the following are true: 

[EINVAL] fsname points to an invalid file-system identifier; 

fsjndex is zero, or invalid; opcode is invalid. 

[EFAULT] buf or fsname point to an invalid user address. 

DIAGNOSTICS 

Upon successful completion, sysfs returns the file-system type index if the opcode 
is GETFSIND, a value of 0 if the opcode is GETFSTYP, or the number of file system 
types configured if the opcode is GETNFSTYP. Otherwise, a value of -1 is returned 
and ermo is set to indicate the error. 
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NAME 

time - get time 

SYNOPSIS 

♦include <sys/types . h> 

timejt time (tloc) 
long *tloc; 

DESCRiPTiON 

time returns the value of time in seconds since 00:00:00 GMT, January 1, 1970. 

If tloc is non-zero, the return value is also stored in the location to which tloc 
points. 

SEE ALSO 

stime(2). 

WARNING 

time fails and its actions are undefined if tloc points to an illegal address. 
DIAGNOSTICS 

Upon successful completion, time returns the value of time. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAIME 

times - get process and child process times 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/tiines . h> 

long times (buffer) 
struct tms *buffer; 

DESCRIPTION 

times fills the structure pointed to by buffer with time-accounting information. 
The following are the contents of this structure: 

struct tms { 

timejt tms_utime; 
timejt tms_stime; 
timejt t:ms_jcutime/ 
timejt tmsjcstime; 

}; 

This information comes from the calling process and each of its terminated child 
processes for which it has executed a wait. All times are reported in clock ticks 
per second. Clock ticks are a system-dependent parameter. The specific value for 
an implementation is defined by the variable HZ, found in the include file 
param.h. 

tmsjLtime is the CPU time used while executing instructions in the user space of 
the calling process. 

tms stime is the CPU time used by the system on behalf of the calling process. 
tmsjMtime is the sum of the tms_utimes and tms_cutimes of the child processes. 
tmsjcstime is the sum of the tms_stimes and tms_cstimes of the child processes. 
[EFAULT] times will fail if buffer points to an illegal address. 

SEE ALSO 

exec(2), fork(2), time(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, times returns the elapsed real time, in clock ticks 
per second, from an arbitrary point in the past (e.g., system start-up time). This 
point does not change from one invocation of times to another. If times fails, a 
- 1 is returned and errno is set to indicate the error. 
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NAME 

uadmin - administrative control 

SYNOPSIS 

♦include <sys/uadmin . h> 

int uadmin (and, fen, indep) 
int and, foi, mdep; 

DESCRIPTION 

uadmin provides control for basic administrative functions. This system call is 
tightly coupled to the system administrative procedures and is not intended for 
general use. The argument mdep is provided for machine-dependent use and is 
not defined here. 

As specified by and, the following commands are available: 

A__SHUTDOWN The system is shutdown. All user processes are killed, the buffer 
cache is flushed, and the root file system is unmounted. The 
action to be taken after the system has been shut down is 
specified by fen. The functions are generic; the hardware capa- 
bilities vary on specific machines. 

AD_HALT Halt the processor and turn off the power. 

AD_BCX)T Reboot the system, using /unix. 

ADJBOOT Interactive reboot; user is prompted for system 
name. 

A_REB(X)T The system stops immediately without any further processing. 
The action to be taken next is specified by fen as above. 

A^REMOUNT The root file system is mounted again after having been fixed. 
This should be used only during the startup process. 

uadmin fails if any of the following are true: 

[EPERM] The effective user ID is not super-user. 

DIAGNOSTICS 

Upon successful completion, the value returned depends on and as follows: 

A_SHUTDOWN Never returns. 
A_REBCX)T Never returns. 

A_^REMOUNT 0 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

ulimit - get and set user limits 

SYNOPSIS 

long ulimit (cmd, newlimit) 

int cand; 

long newlimit; 

DESCRIPTION 

This function provides for control over process limits. The and values available 
are: 

1 Get the regular file size limit of the process. The limit is in units of 512-byte 
blocks and is inherited by child processes. Files of any size can be read. 

2 Set the regular file size limit of the process to the value of newlimit. Any 
process may decrease this limit, but only a process with an effective user ID 
of super-user may increase the limit, ulimit fails and the limit is 
unchanged if a process with an effective user ID other than super-user 
attempts to increase its regular file size limit. [EPERMl 

3 Get the maximum possible break value [see brk(2)]. 

4 Get the current value of the maximum number of open files per process 
configured in the system. 

SEE ALSO 

brk(2), write(2). 

WARNING 

ulimit is effective in limiting the growth of regular files. Pipes are ctirrently lim- 
ited to 5,120 bytes. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 
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NAME 

umask - set and get file creation mask 

SYNOPSIS 

int imvask (cxnask) 
int cmask; 

DESCRIPTION 

umask sets the process's file mode creation mask to cmask and returns the previ- 
ous value of the mask. Only the low-order 9 bits of cmask and the file mode crea- 
tion mask are used. 

SEE ALSO 

chmcxKZ), creat(2), inknod(2), open(2). 
inkdird), sh(l) in the User's Reference Manual 

DIAGNOSTICS 

The previous value of the file mode creation mask is returned. 
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NAME 

umount - unmount a file system 

SYNOPSIS 

int lanoiint (file) 
char *file; 

DESCRIPTION 

lunount requests that a previously mounted file sjrstem contained on the block 
special device or directory identified by file be unmounted, file is a pointer to a 
path name. After unmounting the file system, the directory upon which the file 
system was mounted reverts to its ordinary interpretation. 

umount may be invoked only by the super-user. 

umount will fail if one or more of the following are true: 



[EPERM] 


The process's effective user ID is not super-user. 


[EINVAL] 


file does not exist. 


[ENOTBLK] 


file is not a block special device. 


[EINVAL] 


file is not mounted. 


[EBUSY] 


A file on file is busy. 


lEFAULTl 


file points to an illegal address. 


[EREMOTE] 


file is remote. 


[ENOLINK] 


file is on a remote machine, and the link to that machine is no 




longer active. 


[EMULTIHOP] 


Components of the path pointed to by file require hopping to 




multiple remote machines. 



SEE ALSO 

mount(2). 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

unaxne - get name of current UNIX system 

SYNOPSIS 

tinclude <sys/utsnaine.h> 

int unaune (name) 
struct utsname *nanie; 

DESCRIPTION 

uname stores information identifying the current UNIX system in the structure 
pointed to by name, 

uname uses the structure defined in <sys/utsnaine.h> whose members are: 

char sysname [ 9 ] ; 
char ncxlenaine [ 9 ] ; 
char release [ 9 ] ; 
char version [ 9 ] ; 
char machine [9]; 

uname returns a null-terminated character string naming the current UNIX system 
in the character array sysname. Similarly, nodename contains the name that the 
system is known by on a communications network, release and version further 
identify the operating system, machine contains a standard name that identifies 
the hardware that the UNIX system is running on. 

[EFAULT] uname will fail if name points to an invalid address. 

SEE ALSO 

uname(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 
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NAME 

unlink - remove directory entry 

SYNOPSIS 

int unlink (path) 
char *path; 

DESCRIPTION 

unlink removes the directory entry named by the path name pointed to by path. 
The named file is unlinked imless one or more of the following are true: 
[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENTl The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the link to 

be removed. 

[EACCES] The parent directory has the sticky bit set and 

the file is not writable by the user and 
the user does not own the parent directory and 
the user does not own the file and 
the user is not superuser 

[EPERM] The named file is a directory and the effective user ID of the pro- 

cess is not super-user. 

[EBUSYl The entry to be unlinked is the mount point for a mounted file 

system. 

[ETXTBSY] The entry to be unlinked is the last link to a pure procedure 
(shared text) file that is being executed. 

[EROFS] The directory entry to be unlinked is part of a read-only file sys- 

tem. 

[EFAULT] path points outside the process's allocated address space. 

[EINTR] A signal was caught during the unlink system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

When all links to a file have been removed and no process has the file open, the 
space occupied by the file is freed and the file ceases to exist. If one or more 
processes have the file open when the last link is removed, the removal is post- 
poned until all references to the file have been closed. 

SEE ALSO 

close(2), link(2), qpen(2). 

rmd) in the User's Reference Manual 
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DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and ^rno is set to indicate the error. 
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NAME 

ustat - get file system statistics 

SYNOPSIS 

♦include <sys/types.h> 
♦include <ustat.h> 



int ustat (dev, bu£) 

dev_t dev; 

struct ustat *buf ; 

DESCRIPTION 

ustat returns information about a moimted file system, dev is a device number 
identifying a device containing a mounted file system, huf is a pointer to a ustat 
structure that includes the following elements: 

daddrj:f_jtfree; /* Total free blocks */ 

ino_t f_tinode; /* Nuntoer of free inodes */ 

char f__fnaxneI6] ; /* Filsys name */ 

char f_fpack[6]; /* Filsys pack name */ 

ustat will fail if one or more of the following are true: 

[EINVAL] dev is not the device number of a device containing a mounted 

file system. 

[EFAULT] huf points outside the process's allocated address space. 

[EINTR] A signal was caught during a ustat system call. 

[ENOLINK] dev is on a remote machine and the link to that machine is no 
longer active. 

[ECOMM] dev is on a remote machine and the link to that machine is no 

longer active. 

SEE ALSO 

stat(2), fs(4). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 



io/a9 



Page 1 



utime(2) 



utime(2) 



NAME 

utiine - set file access and modification times 

SYNOPSIS 

tinclude <sys/types . h> 
int utiine (path, times) 
char 't'path; 

struct utinbuf times; 
DESCRIPTION 

path points to a path name naming a file, utime sets the access and modification 
times of the named file. 

If times is NULL, the access and modification times of the file are set to the current 
time. A process must be the owner of the file or have write permission to use 
utime in this manner. 

If times is not null, times is interpreted as a pointer to a utimbuf structure and 
the access and modification times are set to the values contained in the desig- 
nated structure. Only the owner of the file or the super-user may use utime this 
way. 

The times in the following structure are measured in seconds since 00:00:00 GMT, 
Jan. 1, 1970. 

struct utimbuf { 

timejt actime; /* access time */ 
timejt modtime; /* modification time */ 

}; 

utime will fail if one or more of the following are true: 

[ENOENT] The named file does not exist. 

[ENOTDIRl A component of the path prefix is not a directory. 

[EACCES] Search permission is denied by a component of the path prefix. 

[EPERM] The effective user ID is not super-user and not the owner of the 

file and times is not null 

[EACCES] The effective user ID is not super-user and not the owner of the 

file and times is NULL and write access is denied. 

[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] times is not NULL and points outside the process's allocated 

address space. 

[EFAULT] path points outside the process's allocated address space. 

[EINTR] A signal was caught during the utime system call. 

[ENOLINK] path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 
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SEE ALSO 

stat(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and erma is set to indicate the error. 
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NAI\AE 

wait - wait for child process to stop or terminate 

SYNOPSiS 

int wait (stat_loc) 
int *stat_loc; 

DESCRIPTION 

wait suspends the calling process until until one of the immediate children ter- 
minates or until a child that is being traced stops^ because it has hit a break point. 
The wait system call will return prematurely if a signal is received and if a child 
process stopped or terminated prior to the call on wait, return is immediate. 

If Stat Joe is non-zero, 16 bits of information called status are stored in the low 
order 16 bits of the location pointed to by statjoc, status can be used to differen- 
tiate between stopped and terminated child processes and if the child process ter- 
minated, status identifies the cause of termination and passes useful information 
to the parent. This is accomplished in the following manner: 

If the child process stopped, the high order 8 bits of status will contain the 
number of the signal that caused the process to stop and the low order 8 
bits will be set equal to 0177. 

If the child process terminated due to an exit call, the low order 8 bits of 
status will be zero and the high order 8 bits will contain the low order 8 
bits of the argument that the child process passed to exit [see exit (2)]. 

If the child process terminated due to a signal, the high order 8 bits of 
status will be zero and the low order 8 bits will contain the number of the 
signal that caused the termination. In addition, if the low order seventh bit 
(i.e., bit 200) is set, a "core image" will have l^een produced [see sig- 
nal(2)]. 

If a parent process terminates without waiting for its child processes to terminate, 
the parent process ID of each child process is set to 1. This means the initializa- 
tion process inherits the child processes [see intro(2)]. 

wait will fail and return immediately if one or more of the following are true: 
[ECTILD] The calling process has no existing imwaited-for child processes. 

SEE ALSO 

exec(2), exit(2), f ork(2), intro(2), pause(2), ptrace(2), signal(2). 

NOTES 

wait fails and its actions are undefined if statjoc points to an invalid address. 
See NOTES in signal(2). 

DIAGNOSTICS 

If wait returns due to the receipt of a signal, a value of -1 is returned to the cal- 
ling process and ermo is set to EINTR. If wait returns due to a stopped or ter- 
minated child process, the process ID of the child is returned to the calling pro- 
cess. Otherwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

write - write on a file 

SYNOPSIS 

int write (fildes, buf , nbyte) 
int fildes; 
char *buf ; 
unsigned nbyte; 



write (2) 



DESCRIPTION 

fildes is a file descriptor obtained from a creat(2), open(2), di:qp(2), fcntl(2), or 
pipe(2) system call. 

write attempts to write nbyte bytes from the buffer pointed to by buf to the file 
associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds from the posi- 
tion in the file indicated by the file pointer. Upon return from write, the file 
pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the current 
position. The value of a file pointer associated with such a device is undefined. 

If the O APPEND flag of the file status flags is set, the file pointer will be set to 
the end of the file prior to each write. 

For regular files, if the 0_SYNC flag of the file status flags is set, the write will not 
return until both the file data and file status have been physically updated. This 
function is for special applications that require extra reliability at the cost of per- 
formance. For block special files, if O SYNC is set, the write will not return until 
the data has been physically updated. 

A write to a regular file will be blocked if mandatory file/record locking is set 
[see chnod(2)], and there is a record lock owned by another process on the seg- 
ment of the file to be written. If O NDELAY is not set, the write will sleep imtil 
the blocking record lock is removed. 

For STREAMS [see intro(2)] files, the operation of write is determined by the 
values of the minimum and maximum nbyte range ("packet size") accepted by the 
stream. These values are contained in the topmost stream module. Unless the 
user pushes [see I PUSH in streamio(7)] the topmost module, these values can 
not be set or tested from user level. If nbyte falls within the packet size range, 
nbyte bytes will be written. If nbyte does not fall within the range and the 
minimum packet size value is zero, write will break the buffer into maximum 
packet size segments prior to sending the data downstream (the last segment may 
contain less than the maximum packet size). If nbyte does not fall within the 
range and the minimum value is non-zero, write will fail with errno set to 
ERANGE. Writing a zero-length buffer (nbyte is zero) sends zero bytes with zero 
returned. 

For STREAMS files, if O NDELAY is not set and the stream can not accept data (the 
stream write queue is full due to internal flow control conditions), write will 
block until data can be accepted. O NDELAY will prevent a process from blocking 
due to flow control conditions. If O NDELAY is set and the stream can not accept 
data, write will fail. If O NDELAY is set and part of the buffer has been written 
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when a condition in which the stream can not accept additional data occurs, 
write will terminate and return the number of bytes written. 

write will fail and the file pointer will remain imchanged if one or more of the 
following are true: 

[EAGAIN] Mandatory file/record locking was set, O NDELAY was set, and 

there was a blocking record lock. 

[EAGAINl Total amount of system memory available when reading via raw 

lO is temporarily insufficient. 

[EAGAIN] Attempt to write to a stream that can not accept data with the 
O^NDELAY flag set. 

[EBADF] fiUes is not a valid file descriptor open for writing. 

[EDEADLKl The write was going to go to sleep and cause a deadlock situa- 
tion to occur. 

lEFAULT] huf points outside the process's allocated address space. 

[EFBIG] An attempt was made to write a file that exceeds the process's 

file size limit or the maximum file size [see ulimit(2)]. 

[EINTR] A signal was caught during the write system call. 

[EINVAL] Attempt to write to a stream linked below a multiplexor. 

[ENOLCK] The system record lock table was full, so the write could not go 
to sleep imtil the blocking record lock was removed. 

[H^OLMK] fiUes is on a remote machine and the link to that machine is no 
longer active. 

[ENOSR] Attempt to write to a stream with insufficient STREAMS memory 

resources available in the system. 

[S^JOSPC] During a write to an ordinary file, there is no free space left on 

the device, 

lO^XIQl A hangup occurred on the stream being written to. 

[m'IPE and ^PIPE signal] 

An attempt is made to write to a pipe that is not open for read- 
ing by any process. 

[ERANGE] Attempt to write to a stream with nhyte outside specified 

minimum and maximum write range, and the minimum value is 
non-zero. 

If a write requests that more bytes be written than there is room for (e.g., the 
ulimit [see ulimit(2)] or the physical end of a medium), only as many bytes as 
there is room for will be written. For example, suppose there is space for 20 
bytes more in a file before reaching a limit. A write of 512-bytes will return 20. 
llie next wite of a non-zero number of bytes will give a failure return (except as 
noted below). 
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If the file being written is a pipe (or FIFO) and the 0_^NDELAY flag of the file flag 
word is set, then write to a full pipe (or FIFO) will return a count of 0. Otherwise 
(0_NDELAY clear), writes to a full pipe (or FIFO) will block until space becomes 
available. 

A write to a STREAMS file can fail if an error message has been received at the 
stream head. In this case, ermo is set to the value included in the error message. 

SEE ALSO 

creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2), pipe(2), uliinit(2). 
DIAGNOSTICS 

Upon successful completion the number of bytes actually written is returned. 
Otherwise, -1 is returned and ermo is set to indicate the error. 
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NAME 



intro - introduction to functions and libraries 



DESCRIPTION 



This section describes functions found in various libraries, other than those func- 
tions that directly invoke UNIX system primitives, which are described in Sec- 
tion 2 of this volume. Function declarations can be obtained from the #include 
files indicated on each page. Certain major collections are identified by a letter 
after the section number: 

(3C) These functions, together with those of Section 2 and those marked (3S), 
constitute the standard C library, libc, which is automatically linked by 
the C compilation system. The standard C library is implemented as an 
archive, libc. a. 

(3S) These functions constitute the "standard I/O package" [see stdio(3S)]. 

(3E) These functions constitute the ELF access library, libelf. This library is 
not automatically linked by the C compilation system. Specify -lelf on 
the cc command line to link with this library. 

(3G) These functions constitute the general-purpose library, libgen. This 
library is not automatically linked by the C compilation system. Specify 
-Igen on the cc command line to link with this library. 

(3M) These functions constitute the math library, libm. [See intro(3M) and 
roath(5).l This library is not automatically linked by the C compilation sys- 
tem. Use the -Im option on the cc command line to link with the libm 
library. 

(3X) Specialized libraries. The files in which these libraries are found are given 
on the appropriate pages. 



A character is any bit pattern able to fit into a byte on the machine. The null 
character is a character with value 0, conventionally represented in the C 
language as \0. A character array is a sequence of characters. A null-terminated 
character array (a string) is a sequence of characters, the last of which is the null 
character. The null string is a character array containing only the terminating 
null character. A NULL pointer is the value that is obtained by casting 0 into a 
pointer. C guarantees that this value will not match that of any legitimate 
pointer, so many functions that return pointers return NULL to indicate an error. 
The macro NULL is defined in stdio.h. Types of the form size_t are defined in 
the appropriate header files. 



DEFINITIONS 



FILES 



INCDIR 
LIBDIR 

LIBDIR/ lihc. a 
L/BDJR/libgen.a 
LIBDIR/ lihm. a 



usually /usr/ include 
usually /usr/ccs/lib 



10/89 



Page 1 



Intro (3) 



intro(3) 



SEE ALSO 

ar(l), cc(l), ld(l), lint(l), rund), intro(2), intro(3M), 8tdio(3S), inath(5). 
The "C Compilation System" chapter in the Programmer's Guide: ANSI C and Pro- 
gramming Support Tools. 

DIAGNOSTICS 

Error handling varies, for functions that return floating-point values, according to 
compilation mode. Under the -Xt (default) option to cc, these functions return 
the conventional values 0, IHUGE, or NaN when the function is undefined for the 
given arguments or when the value is not representable. In the -Xa and -Xc 
compilation modes, ±HUGE__yAL is returned instead of ±HUGE. (HDGE^VAL and 
HUGE are defined in xnath.h to be infinity and the largest-magnitude single- 
precision number, respectively.) 

NOTES 

None of the functions, external variables, or macros should be redefined in the 
user's programs. Any other name may be redefined without affecting the 
behavior of other library functions, but such redefinition may conflict with a 
declaration in an included header file. 

The header files in INCDIR provide function protot5^es (function declarations 
including the types of arguments) for most of the functions listed in this manual. 
Function prototypes allow the compiler to check for correct usage of these func- 
tions in the user's program. The lint program checker may also be used and 
will report discrepancies even if the header files are not included with #include 
statements. Definitions for Sections 2, 3C, and 3S are checked automatically. 
Other definitions can be included by using the -1 option to lint. (For example, 
-Im includes definitions for libin.) Use of lint is highly recommended. 

Users should carefully note the difference between STREAMS and stream. 
STREAMS is a set of kernel mechanisms that support the development of network 
services and data communication drivers. It is composed of utility routines, ker- 
nel facilities, and a set of data structures. A stream is a file with its associated 
buffering. It is declared to be a pointer to a type FILE defined in stdio.h. 

In detailed definitions of components, it is sometimes necessary to refer to sym- 
bolic names that are implementation-specific, but which are not necessarily 
expected to be accessible to an application program. Many of these symbolic 
names describe boundary conditions and system limits. 

In this section, for readability, these implementation-specific values are given 
symbolic names. These names always appear enclosed in curly brackets to distin- 
guish them from symbolic names of other implementation-specific constants that 
are accessible to application programs by header files. These names are not 
necessarily accessible to an application program through a header file, although 
they may be defined in the documentation for a particular system. 

In general, a portable application program should not refer to these symbolic 
names in its code. For example, an application program would not be expected 
to test the length of an argument list given to a routine to determine if it was 
greater than {ARG_MAX}. 
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NAME 

a641, 164a - convert between long integer and base-64 ASCII string 

SYNOPSIS 

finclude <stdlib.h> 

long a641 (const char '•'s); 

char '*'164a (long 1) ; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII characters. 
These characters define a notation by which long integers can be represented by 
up to six characters; each character represents a "digit" in a radix-^4 notation. 

The characters used to represent "digits" are . for 0, / for 1, 0 through 9 for 
2-11, A through Z for 12-37, and a through z for 38-63. 

a641 takes a pointer to a null-terminated base-64 representation and returns a 
corresponding long value. If the string pointed to by s contains more than six 
characters, a641 will use the first six. 

a641 scans the character string from left to right with the least significant digit on 
the left, decoding each character as a 6-bit radix-64 number. 

164a takes a long argument and returns a pointer to the corresponding base-64 
representation. If the argument is 0, 164a returns a pointer to a null string. 

NOTES 

The value returned by 164a is a pointer into a static buffer, the contents of which 
are overwritten by each call. 
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NAME 

abort - generate an abnormal termination signal 

SYNOPSIS 

♦include <stdlib.h> 

void abort (void) ; 
DESCRIPTION 

abort first closes all open files, stdio(3S) streams, and directory streams, if pos- 
sible, then causes the signal SIGABRT to be sent to the calling process. 

SEE ALSO 

sdb(l), exit(2), kill(2), signal(2), stdio(3S). 
sh(l) in the User's Reference Manual, 

DIAGNOSTICS 

If SIGS^T is neither caught nor ignored, and the current directory is writable, a 
core dump is produced and the message abort - core duxrped is written by the 
shell [see sh(l)]. 
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NAME 

abs, labs - return integer absolute value 

SYNOPSIS 

♦include <stdlib.h> 

int abs (int val); 

long labs (long Ival) ; 

DESCRIPTION 

abs returns the absolute value of its int operand, labs returns the absolute 
value of its long operand. 

SEE ALSO 

floorOM). 

NOTES 

In 2's-complement representation, the absolute value of the largest magnitude 
negative integral value is undefined. 
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NAME 

addseverity - build a list of severity levels for an application for use with 
fmtinsg 

SYNOPSIS 

finclude <£nttinsg.h> 

int addseverity (int severity, const char * string) ; 
DESCRIPTION 

The addseverity function builds a list of severity levels for an application to be 
used with the message formatting facility, fmtnvsg. severity is an integer value 
indicating the seriousness of the condition, and string is a pointer to a string 
describing the condition (string is not limited to a specific size). 

If addseverity is called with an integer value that has not been previously 
defined, the function adds that new severity value and print string to the existing 
set of standard severity levels. 

If addseverity is called with an integer value that has been previously defined, 
the function redefines that value with the new print string. Previously defined 
severity levels may be removed by suppl5dng the NULL string. If addseverity is 
called with a negative number or an integer value of 0, 1, 2, 3, or 4, the function 
fails and returns -1. The values 0-4 are reserved for the standard severity levels 
and cannot be modified. Identifiers for the standard levels of severity are: 

H1_HALT indicates that the application has encountered a severe 
fault and is halting. Produces the print string HALT. 

MM__ERROR indicates that the application has detected a fault. Pro- 
duces the print string ERROR. 

MMMWARNING indicates a condition that is out of the ordinary, that might 
be a problem, and should be watched. Produces the print 
string WARNING. 

WM_INFO provides information about a condition that is not in error. 
Produces the print string INFO. 

MM_NOSEV indicates that no severity level is supplied for the message. 

Severity levels may also be defined at run time using the SEy_LEVEL environment 
variable [see fmtmsgOC)]. 

EXAMPLES 

When the function addseverity is used as follows: 

addseverity (7, "ALERT") 

the following call to f mtmsg: 

fintinsg(MM__PRINT, "UXicat", 7, "invalid syntax", "refer to 
manual", "UX:cat :001") 

produces: 
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UX:cat: ALERT: invalid syntax 

TO FIX: refer to manual UX: cat: 001 

SEE ALSO 

fratmsgOC), printf(3S). 

DIAGNOSTICS 

addseverity returns ^MJOK on success or IfiJIOTOK on failure. 
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NAME 

atexit - add program termination routine 

SYNOPSIS 

♦include <stdlib.h> 

int atexit (void (*func) (void) ) ; 
DESCRIPTION 

atexit adds the function func to a list of functions to be called without argu- 
ments on normal termination of the program. Normal termination occurs by 
either a call to the exit system call or a return from nain. At most 32 functions 
may be registered by atexit; the functions will be called in the reverse order of 
their registration. 

atexit returns 0 if the registration succeeds, nonzero if it fails. 

SEE ALSO 

exit(2). 
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NAME 



bsearch ~ binary search a sorted table 



SYNOPSIS 



♦include <stdlib.h> 

void *bsearch (const void *key, const void ♦base, size__t nel, 
size_t size, int (♦coinpar) (const void const void *) ); 



bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm B. 
It returns a pointer into a table (an array) indicating where a datum may be 
found or a null pointer if the datum cannot be found. The table must be previ- 
ously sorted in increasing order according to a comparison fimction pointed to by 
compar. key points to a datum instance to be sought in the table, base points to 
the element at the base of the table, nel is the number of elements in the table. 
size is the number of bytes in each element. The function pointed to by compar is 
called with two arguments that point to the elements being compared. The fimc- 
tion must return an integer less than, equal to, or greater than 0 as accordingly 
the first argument is to be considered less than, equal to, or greater than the 
second. 



The example below searches a table containing pointers to nodes consisting of a 
string and its length. The table is ordered alphabetically on the string in the node 
pointed to by each entry. 

This program reads in strings and either finds the corresponding node and prints 
out the string and its length, or prints an error message. 

♦include <stdio.h> 
♦include <stdlib.h> 
♦include <string.h> 

struct node { /* these are stored in the table */ 



DESCRIPTION 



EXAMPLE 



char * string; 
int length; 



}; 

static struct node table [] 
{ 



/* table to be searched */ 



{ "asparagus", 10 }, 

{ "beans", 6 >, 

{ "tonato", 7 }, 

{ "watermelon", 11 }, 



inainO 
{ 



struct node *nc)dejptr, node; 

/* routine to coirpare 2 nodes */ 

static int node_conpare (const void *, const void *); 
char str_space[20] ; /* space to read string into */ 
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node. string = str_space; 

vrtiile (scanf ("%20s", node. string) != EOF) { 
nodejptr = bsearch ( &node, 

table, sizeof (table )/sizeof (struct node), 
sizeof (struct node), nodejccirpare) ; 
if (nodejptr != NULL) { 

(void) printf ("string = %20s, length = %d\n", 
node_j>tr->string, node_j>tr-->length) ; 

} else { 

(void) printf ( "not found : %20s\n" , node . string) ; 

} 

} 

return (0) ; 

> 

/♦ routine to ccnpare two nodes based on an */ 
/* alphabetical ordering of the string field */ 
static int 

node_connpeu:e (const void '•'nodel, const void '<'node2) 
{ 

return (strcnp( 

((const struct node *)nodel)->string, 
((const struct node *)node2)->string) ) ; 

} 

SEE ALSO 

hsearchOO, lsearch(3C), qsort(3C), tsearch(3C). 
DIAGNOSTICS 

A null pointer is returned if the key cannot be found in the table. 

NOTES 

The pointers to the key and the element at the base of the table should be of type 
pointer-io-element. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

If the number of elements in the table is less than the size reserved for the table, 
nel should be the lower number. 
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NAME 

clock - report CPU time used 

SYNOPSIS 

♦include <tiine.h> 

clock_t clock (void) ; 
DESCRIPTION 

clcx:k returns the amount of CPU time (in microseconds) used since the first call 
to clock in the calling process. The time reported is the sum of the user and sys- 
tem times of the calling process and its terminated child processes for which it 
has executed the wait system call, the pclose function, or the system function. 

Dividing the value returned by clock by the constant CLOCKS_PER_SEC, defined 
in the time .h header file, will give the time in seconds. 

SEE ALSO 

tixnes(2), wait(2), popen(3S), systeni(3S). 

NOTES 

The value returned by clock is defined in microseconds for compatibility with 
systems that have CPU clocks with much higher resolution. Because of this, the 
value returned will wrap around after accumulating only 2147 seconds of CPU 
time (about 36 minutes). If the process time used is not available or cannot be 
represented, clock returns the value (clockjt)-l. 
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NAME 

conv : toupper, tolower, ^tovqpper, _tolower, toascii - translate characters 

SYNOPSIS 

♦include <ctype.h> 

int toupper (int c) ; 
int tolower (int c) ; 
int jtoupper (int c) ; 
int jtolower (int c) ; 
int toascii (int c) ; 
DESCRIPTION 

toupper and tolower have as their domain the range of the function getc: all 
values represented in an unsigned char and the value of the macro EOF as 
defined in stdio.h. If the argument of toupper represents a lower-case letter, 
the result is the corresponding upper-case letter. If the argument of tolower 
represents an upper-case letter, the result is the corresponding lower-case letter. 
All other arguments in the domain are returned unchanged. 

The macros _toupper and _tolower accomplish the same things as toupper and 
tolower, respectively, but have restricted domains and are faster. _toupper 
requires a lower-case letter as its argtiment; its result is the corresponding upper- 
case letter. _tolower requires an upper-case letter as its argument; its result is 
the corresponding lower-case letter. Arguments outside the domain cause 
undefined results. 

toascii yields its argument with all bits turned off that are not part of a stan- 
dard 7-bit ASCII character; it is intended for compatibility with other systems. 

toupper, tolower, _toupper, and__tolower are affected by LCjCTYPE. In the C 
locale, or in a locale where shift information is not defined, these functions deter- 
mine the case of characters according to the rules of the ASCII-coded character set. 
Characters outside the ASQI range of characters are returned unchanged. 

SEE ALSO 

ctypeOO, getc(3S), setlocale(3C), environ(5). 
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NAME 

crypt, setkey, encrypt - generate encryption 

SYNOPSIS 

♦include <crypt.h> 

char ♦crypt (const char *key, const char *salt) ; 
void setkey (const char *key) ; 
void encrypt (char *block, int edflag) ; 
DESCRIPTION 

crypt is the password encryption function. It is based on a one-way encryption 
algorithm with variations intended (among other things) to frustrate use of 
hardware implementations of a key search. 

key is the input string to encrypt, for instance, a user's typed password. Only the 
first eight characters are used; the rest are ignored, salt is a two-character string 
chosen from the set a-zA-ZO-9 . /; this string is used to perturb the hashing algo- 
rithm in one of 4096 different ways, after which the input string is used as the 
key to encrypt repeatedly a constant string. The returned value points to the 
encrypted input string. The first two characters of the return value are the salt 
itself. 

The setkey and encrypt functions provide (rather primitive) access to the actual 
hashing algorithm. The argument of setkey is a character array of length 64 con- 
taining only the characters with numerical value 0 and 1. This string is divided 
into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit 
key that is set into the machine. This is the key that will be used with the hash- 
ing algorithm to encrypt the string block with the encrypt function. 

The block argtmient of encrypt is a character array of length 64 containing only 
the characters with numerical value 0 and 1. The argument array is modified in 
place to a similar array representing the bits of the argument after having been 
subjected to the hashing algorithm using the key set by setkey. The argument 
edflag, indicating decryption rather than encryption, is ignored; use encrypt in 
libcrypt [see crypt(3X)] for decryption. 

SEE ALSO 

getpassOO, crypt(3X), passwd(4). 

login(l), passwd(l) in the User's Reference Manual. 

NOTES 

The return value for crypt points to static data that are overwritten by each call. 



10/89 



Page 1 



ctermid(3S) 



ctermid(3S) 



NAME 

ctermid - generate file name for terminal 

SYNOPSIS 

♦include <stdio.h> 

char * ctermid (char *s) ; 
DESCRIPTION 

ctermid generates the path name of the controlling terminal for the current pro- 
cess, and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static area, the contents of 
which are overwritten at the next call to ctermid, and the address of which is 
returned. Otherwise, s is assumed to point to a character array of at least 
L__ctermid elements; the path name is placed in this array and the value of s is 
returned. The constant L_ctentiid is defined in the stdio . h header file. 

SEE ALSO 

ttynameOC). 

NOTES 

The difference between ctermid and ttyname(3C) is that ttyname must be 
handed a file descriptor and returns the actual name of the terminal associated 
with that file descriptor, while ctermid returns a string (/dev/tty) that will refer 
to the terminal if used as a file name. Thus ttyname is useful only if the process 
already has at least one file open to a terminal. 
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NAME 

ctime, Icx^altime, gxntime, asctime, tzset - convert date and time to string 

SYNOPSIS 

♦include <tiine.h> 

char *ctiine (const time_t ♦clock) ; 
struct tm ♦localtiine (const time_t *clock) ; 
struct tm *gmtiine (const tixne_jt *clock) / 
char *asctiine (const struct tm *t:m); 
extern time_t timezone^ alt zone; 
extern int daylight; 
extern char *tzname[2]; 
void tzset (void); 
DESCRIPTION 

ctime, localtiroe, and gmtime accept arguments of type time_t, pointed to by 
clock, representing the time in seconds since 00:00:00 UTC, January 1, 1970. 
ctime returns a pointer to a 26-character string as shown below. Time zone and 
daylight savings corrections are made before the string is generated. The fields 
are constant in width: 

Fri Sep 13 00:00:00 1986\n\0 

localtime and gmtime return pointers to tm structures, described below, local- 
time corrects for the main time zone and possible alternate ("daylight savings") 
time zone; gmtime converts directly to Coordinated Universal Time (UTC), which 
is the time the UNIX system uses internally. 

asctime converts a tm structure to a 26-character string, as shown in the above 
example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the tm structure, are in the 
time.h header file. The structure declaration is: 



/* seconds after the minute - [0, 61] */ 

/♦ for leap seconds */ 
/♦ minutes after the hour - [0, 59] */ 
/* hour since midnight - [0, 23] */ 
/* day of the month - [1, 31] */ 
/* months since January — [0, 11] */ 
/♦ years since 1900 */ 
/* days since Sunday — [0, 6] */ 
/* days since January 1 — [0, 365] */ 
/* flag for alternate daylight */ 

/* savings time ♦/ 



t 


tm { 


int 


tm__sec; 


int 


tm_min; 


int 


tanjhour; 


int 


t:mjnday; 


int 


tmjton; 


int 


t:m_year; 


int 


tmjwday; 


int 


tmjyday; 


int 


tm isdst; 



}; 
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The value of tin_isdst is positive if daylight savings time is in effect, zero if day- 
light savings time is not in effect, and negative if the information is not available. 
(Previously, the value of tin_isdst was defined as non-zero if daylight savings 
time was in effect.) 

The external time_t variable altzone contains the difference, in seconds, 
between Coordinated Universal Time and the alternate time zone. The external 
variable timezone contains the difference, in seconds, between UTC and local 
standard time. The external variable daylight indicates whether time should 
reflect daylight savings time. Both timezone and altzone default to 0 (UTC). 
The external variable daylight is non-zero if an alternate time zone exists. The 
time zone names are contained in the external variable tznaine, which by default 
is set to: 

char *tznaine[2] = { "GMT", " " }; 

These functions know about the peculiarities of this conversion for various time 
periods for the U.S. (specifically, the years 1974, 1975, and 1987). They will handle 
the new daylight savings time starting with the first Simday in April, 1987. 

tzset uses the contents of the environment variable TZ to override the value of 
the different external variables. The function tzset is called by asctime and 
may also be called by the user. See environ(5) for a description of the TZ 
environment variable. 

tzset scans the contents of the environment variable and assigns the different 
fields to the respective variable. For example, the most complete setting for New 
Jersey in 1986 could be 

EST5EDT4 , 116/2 : 00 : 00 , 298/2 : 00 : 00 

or simply 

EST5EDT 

An example of a southern hemisphere setting such as the Cook Islands could be 

KDT9 : 30KST10 : 00 , 63/5 : 00 , 302/20 : 00 

In the longer version of the New Jersey example of TZ, tznaine[0] is EST, 
timezone will be set to 5*60*60, tznanie[ll is EDT, altzone will be set to 
4*60*60, the starting date of the alternate time zone is the 117th day at 2 AM, the 
ending date of the alternate time zone is the 299th day at 2 AM (using zero-based 
Julian days), and daylight will be set positive. Starting and ending times are 
relative to the alternate time zone. If the alternate time zone start and end dates 
and the time are not provided, the days for the United States that year will be 
used and the time will be 2 AM. If the start and end dates are provided but the 
time is not provided, the time will be 2 AM. The effects of tzset are thus to 
change the values of the external variables timezone, altzone, daylight, and 
tzname. ctime, localtiroe, mktime, and strftime will also update these exter- 
nal variables as if they had called tzset at the time specified by the timejt or 
struct tm value that they are converting. 

Note that in most installations, TZ is set to the correct value by default when the 
user logs on, via the local /etc/profile file [see prof ile(4) and timezone(4)]. 
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FILES 

/usr/lib/locale//anguage/LC_TIME - file containing locale specific date and 
time information 

SEE ALSO 

time(2), getenvOC), mktimeOC), putenv(3C), printfOS), setlocaleOC), 
strftiine(3C), c£time(4), prof ile(4), tiinezone(4), environ(5). 

NOTES 

The return values for ctime, localtiine, and gmtixne point to static data whose 
content is overwritten by each call. 

Setting the time during the interval of change from tixnezone to alt zone or vice 
versa can produce unpredictable results. The system administrator must change 
the Julian start and end days annually. 
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NAME 

ctype: isdigit, isxdigit, islower, isi:Q>per, isalpha, isalnunv isspace, 
iscntrl, ispunct, isprint, isgraph^ isascii - character handling 

SYNOPSIS 

♦include <ctype.h> 

int isalphadnt c) ; 
int isupperdnt c) ; 
int is lower (int c) ; 
int isdigit(int c) ; 
int isxdigit (int c) ; 
int isalnum(int c) ; 
int isspace (int c) ; 
int ispunct(int c) ; 
int isprint(int c) ; 
int isgraph(int c) ; 
int iscntrl (int c) ; 
int isascii (int c) ; 
DESCRIPTION 

These macros classify character-coded integer values. Each is a predicate return- 
ing non-zero for true, zero for false. The behavior of these macros, except 
isascii, is affected by the current locale [see setlocale(3C)]. To modify the 
behavior, change the LCJTYPE category in setlocale, that is, setlocale 
(LCjCTYPE, newlocale). In the C locale, or in a locale where character type infor- 
mation is not defined, characters are classified according to the rules of the US- 
ASai 7-bit coded character set. 

The macro isascii is defined on all integer values; the rest are defined only 
where the argument is an int, the value of which is representable as an 
unsigned char, or EOF, which is defined by the stdio.h header file and 
represents end-of-file. 

isalpha tests for any character for which isupper or is lower is true, or 

any character that is one of an implementation-defined set of 
characters for which none of iscntrl, isdigit, ispunct, or 
isspace is true. In the C locale, isalpha returns true only for 
the characters for which isupper or islower is true. 

isupper tests for any character that is an upper-case letter or is one of an 

implementation-defined set of characters for which none of 
iscntrl, isdigit, ispunct, isspace, or islower is true. In 
the C locale, isupper returns true only for the characters defined 
as upper-case ASQI characters. 
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islower 



isdigit 
isxdigit 

isalnisn 

isspace 



ispunct 



tests for any character that is a lower-case letter or is one of an 
implementation-defined set of characters for which none of 
iscntrl, isdigit, ispunct, isspace, or isupper is true. In 
the C locale, islower returns true only for the characters defined 
as lower-case ASCII characters. 

tests for any decimal-digit character. 

tests for any hexadecimal-digit character ([0-9], [A-F] or 
[a-f]). 

tests for any character for which isalpha or isdigit is true 
(letter or digit). 

tests for any space, tab, carriage-return, newline, vertical-tab or 
form-feed (standard white-space characters) or for one of an 
implementation-defined set of characters for which isalnum is 
false. In the c locale, isspace returns true only for the standard 
white-space characters. 



tests for any printing character which is neither a space nor a 
character for which isalnum is true. 

isprint tests for any printing character, including space (" "). 

isgraph tests for any printing character, except space. 

iscntrl tests for any "control character" as defined by the character set. 

isascii tests for any ASQI character, code between 0 and 0177 inclusive. 

All the character classification macros and the conversion functions and macros 
use a table lookup. 

Fimctions exist for all the above-defined macros. To get the function form, the 
macro name must be undefined (e.g., #undef isdigit). 



FILES 



/usr/lib/locale/Zocak/LC_CTYPE 
SEE ALSO 

chrtbl(lM), setlocale(3C), stdioOS), ascii(5), environ(5). 
DIAGNOSTICS 

If the argument to any of the character handling macros is not in the domain of 
the function, the result is imdefined. 
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NAME 

cuserid - get character login name of the user 

SYNOPSIS 

♦include <stdio.h> 

char *cuserid (char *s) ; 
DESCRIPTION 

cuserid generates a character-string representation of the login name that the 
owner of the current process is logged in under. If s is a NULL pointer, this 
representation is generated in an internal static area, the address of which is 
returned. Otherwise, s is assumed to point to an array of at least L_cuserid 
characters; the representation is left in this array. The constant Ljcuserid is 
defined in the stdio.h header file. 

SEE ALSO 

getloginOO, getpwent(3C). 

DIAGNOSTICS 

If the login name cannot be fotmd, cuserid returns a NULL pointer; if s is not a 
NULL pointer, a null character " \0 ' will be placed at s [0] . 
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NAME 

dial - establish an out-going terminal line connection 

SYNOPSIS 

tinclude <dial.h> 

int dial (CALL call) ; 
void undial (int fd) ; 
DESCRIPTION 

dial returns a file-descriptor for a terminal line open for read /write. The argu- 
ment to dial is a CALL structure (defined in the dial.h header file). 

When finished with the terminal line, the calling program must invoke undial to 
release the semaphore that has been set during the allocation of the terminal dev- 
ice. 

The definition of CALL in the dial . h header file is: 
typedef struct { 



struct 


termio *attr; 


/* 


pointer to termio attribute struct */ 


int 


baud; 


/* 


transmission data rate */ 


int 


speed; 


/* 


212A modem: low=300, high=1200 */ 


char 


*line; 


/* 


device name for out-going line */ 


char 


♦telno; 


/* 


pointer to tel-no digits string */ 


int 


modem; 


/* 


specify modem control for direct lines */ 


char 


♦device; 


/* 


unused */ 


int 


dev_len; 


/* unused */ 


} CALL; 









The CALL element speed is intended only for use with an outgoing dialed call, in 
which case its value should be either 300 or 1200 to identify the 113A modem, or 
the high- or low-speed setting on the 212A modem. Note that the 113A modem 
or the low-speed setting of the 21 2A modem will transmit at any rate between 0 
and 300 bits per second. However, the high-speed setting of the 212A modem 
transmits and receives at 1200 bits per second only. The CALL element baud is for 
the desired transmission baud rate. For example, one might set baud to 110 and 
speed to 300 (or 1200). However, if speed is set to 1200, baud must be set to 
high (1200). 

If the desired terminal line is a direct line, a string pointer to its device-name 
should be placed in the line element in the CALL structure. Legal values for 
such terminal device names are kept in the Devices file. In this case, the value of 
the baud element should be set to -1. This value will cause dial to determine the 
correct value from the Devices file. 

The telno element is for a pointer to a character string representing the tele- 
phone number to be dialed. Such numbers may consist only of these characters: 

0-9 dial 0-9 

* dial * 

# dial # 

= wait for secondary dial tone 

-- delay for approximately 4 seconds 
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The CALL element xtodem is used to specify modem control for direct lines. This 
element should be non-zero if modem control is required. The CALL element 
attr is a pointer to a termio structure, as defined in the termio.h header file. 
A NULL value for this pointer element may be passed to the dial function, but if 
such a structure is included, the elements specified in it will be set for the outgo- 
ing terminal line before the connection is established. This setting is often impor- 
tant for certain attributes such as parity and baud-rate. 

The CALL elements device and dev__len are no longer used. They are retained in 
the CALL structure for compatibility reasons. 

FILES 

/etc/uucp/Devices 
/etc/uucp/Systems 
/var/spool/uucp/LCK. Aty-devke 

SEE ALSO 

alarm(2), read(2), write(2). 

terndo(7) in the System Administrator's Reference Manual. 
uucp(lC) in the User's Reference Manual. 
DIAGNOSTICS 

On failure, a negative value indicating the reason for the failure will be returned. 
Mnemonics for these negative indices as listed here are defined in the dial.h 
header file. 



INTRPT 


-1 


/* 


internipt occurred */ 


D HUNG 


-2 


/* 


dialer hung (no return from write) */ 


NO ANS 


-3 


/* 


no answer within 10 seconds */ 


ILL BD 


-4 


/* 


illegal baud-rate */ 


A PROB 


-5 


/* 


acu problem (openO failure) */ 


L__PROB 


-6 


/* 


line problem (openO failure) */ 


NO Ldv 


-7 


/* 


can't open Devices file */ 


DV NT A 


-8 


/* 


requested device not available */ 


DV NT K 


-9 


/* 


requested device not known */ 


NO BD A 


-10 


/* 


no device available at requested baud */ 


NO BD K 


-11 


/* 


no device known at requested baud */ 


DV NT E 


-12 


/♦ 


requested speed does not match */ 


BAD SYS 


-13 


/* 


system not in Systems file*/ 



NOTES 

Including the dial.h header file automatically includes the termio.h header file. 

An alarm(2) system call for 3600 seconds is made (and caught) within the dial 
module for the purpose of "touching" the LCK. . file and constitutes the device 
allocation semaphore for the terminal device. (Dtherwise, uucp(lC) may simply 
delete the LCK. . entry on its 90-minute clean-up rounds. The alarm may go off 
while the user program is in a read(2) or write(2) system call, causing an 
apparent error return. If the user program expects to be around for an hour or 
more, error returns from reads should be checked for (errno=EINTR) , and the 
read possibly reissued. 
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NAME 

dif f time - computes the difference between two calendar times 

SYNOPSIS 

♦include <tiine.h> 

double dif f time (time_t timel, time__t timeO) ; 
DESCRIPTION 

dif ftiroe computes the difference between two calendar times, dif ftime returns 
the difference (timel-timeO) expressed in seconds as a double. This function is 
provided because there are no general arithmetic properties defined for type 
timejt. 

SEE ALSO 

ctimeOQ. 
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NAME 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir - 
directory operations 

SYNOPSIS 

♦include <dirent.h> 

DIR *opendir (const char *f ilename) ; 
struct dirent *readdir (DIR *dirp) ; 
long telldir (DIR *dirp) ; 
void seekdir (DIR *dirp, long loc) ; 
void rewinddir (DIR *dirp) ; 
int closedir (DIR *dirp) ; 
DESCRIPTION 

opendir opens the directory named by filename and associates a directory stream 
with it. opendir returns a pointer to be used to identify the directory stream in 
subsequent operations. The directory stream is positioned at the first entry. A 
null pointer is returned if filename cannot be accessed or is not a directory, or if it 
cannot roalloc(3C) enough memory to hold a DIR structure or a buffer for the 
directory entries. 

readdir returns a pointer to the next active directory entry and positions the 
directory stream at the next entry. No inactive entries are returned. It returns 
NULL upon reaching the end of the directory or upon detecting an invalid location 
in the directory, readdir buffers several directory entries per actual read opera- 
tion; readdir marks for update the st_jatinie field of the directory each time the 
directory is actually read. 

telldir returns the current location associated with the named directory stream. 

seekdir sets the position of the next readdir operation on the directory stream. 
The new position reverts to the position associated with the directory stream at 
the time the telldir operation that provides loc was performed. Values 
returned by telldir are valid only if the directory has not changed because of 
compaction or expansion. This situation is not a problem with System V, but it 
may be a problem with some file system types. 

rewinddir resets the position of the named directory stream to the beginning of 
the directory. It also causes the directory stream to refer to the current state of 
the corresponding directory, as a call to opendir would. 

closedir closes the named directory stream and frees the DIR structure. 

The following errors can occur as a result of these operations. 

opendir returns NULL on failure and sets errno to one of the following values: 

ENOTDIR A component of filename is not a directory. 

EACCES A component of filename denies search permission. 
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EACCES Read permission is denied on the specified directory. 

EMFILE The maximum number of file descriptors are currently 

open. 

ENFILE The system file table is fiiU. 

EFAULT filename points outside the allocated address space. 

ENOENT A component of filename does not exist or is a null path- 

name. 

readdir returns NULL on failure and sets errno to one of the following values: 

ENOENT The current file pointer for the directory is not located at a 

valid entry. 

EBADF The file descriptor determined by the DIR stream is no 

longer valid. This result occurs if the DIR stream has been 
closed. 

telldir, seekdir, and closedir return -1 on failure and set errno to the fol- 
lowing value: 

EBADF The file descriptor determined by the DIR stream is no 

longer valid. This results if the DIR stream has been closed. 

EXAMPLE 

Here is a sample program that prints the names of all the files in the current 
directory: 

♦include <stdio.h> 
tinclude <dirent.h> 

mainO 
{ 

DIR *dirp; 

struct dirent *direntp; 
dirp = opendir ( " . " ) ; 

%rtiile ( (direntp = readdir ( dirp )) != NULL ) 
(void)printf ( "%s\n"r direntp->d_name )/ 
closedir ( dirp ) ; 
return (0) ; 

} 

SEE ALSO 

getdents(2), dirent(4). 

NOTES 

rewdLnddir is implemented as a macro, so its function address cannot be taken. 
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NAME 

div, Idiv - compute the quotient and remainder 

SYNOPSIS 

♦include <stdlib.h> 

div_t div (int nuiner, int denom) ; 
Idivjt Idiv (long int numer, long int denom) ; 
DESCRIPTION 

div computes the quotient and remainder of the division of the numerator numer 
by the denominator denom. This function provides a well-defined semantics for 
the signed integral division and remainder operations, unlike the 
implementation-defined semantics of the built-in operations. The sign of the 
resulting quotient is that of the algebraic quotient, and, if the division is inexact, 
the magnitude of the resulting quotient is the largest integer less than the magni- 
tude of the algebraic quotient. If the result cannot be represented, the behavior is 
undefined; otherwise, quotient ♦ denom + remainder will equal numer. 

div returns a structure of type div_t, comprising both the quotient and 
remainder: 

typedef struct div_t { 

int quot; /*quotient*/ 

int rem; /*remainder*/ 
} div_t/ 

Idiv is similar to div, except that the arguments and the members of the 
returned structure (which has type Idivjt) all have type long int. 
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NAME 

dr£uid48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48^ 
lcong48 - generate uniformly distributed pseudo-random numbers 

SYNOPSIS 

tinclude <stdlib.h> 

double drand48 (void) ; 

double erand48 (lonsigned short xsubi[3] ); 
long lrand48 (void) ; 

long nrand48 (unsigned short xsubi[3] ); 
long inrand48 (void) ; 

long jrcLnd48 (unsigned short xsubi[3] ); 
void srand48 (long seedval) ; 

unsigned short *seed48 (unsigned short seedl6v[3] ); 
void lcong48 (unsigned short param[7] ) ; 
DESCRIPTION 

This family of fimctions generates pseudo-random numbers using the well-known 
linear congruential algorithm and 48-bit integer arithmetic. 

Functions drand48 and erand48 return non-negative double-precision floating- 
point values uniformly distributed over the interval [0.0, 1.0). 

Functions lrand48 and nrand48 return non-negative long integers uniformly dis- 
tributed over the interval [0, 2^^). 

Functions xnrand48 and jrand48 return signed long integers uniformly distri- 
buted over the interval [-2^\ 2^^). 

Functions srand48, seed48, and lcong48 are initialization entry points, one of 
which should be invoked before either drand48, lrand48, or mrand48 is called. 
(Although it is not recommended practice, constant default initializer values will 
be supplied automatically if dr«uid48, lrand48, or mrand48 is called without a 
prior call to an initialization entry point.) Functions erand48, nrand48, and 
jrand48 do not require an initialization entry point to be called first. 

All the routines work by generating a sequence of 48-bit integer values, X„ 
according to the linear congruential formula 

Xn+i = (flX„ + c)^^ n>0. 

The parameter m=2^; hence 48-bit integer arithmetic is performed. Unless 
lcong48 has been invoked, the multiplier value a and the addend value c are 
given by 

a = 5DEECE66Di6 = 2736731631558 
C = = 138. 

The value returned by any of the functions drand48, erand48, lrand48, 
nrand48, mrand48, or jrand48 is computed by first generating the next 48-bit X, 
in the sequence. Then the appropriate number of bits, according to the type of 
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data item to be returned, are copied from the high-order (leftmost) bits of X, and 
transformed into the returned value. 

The functions drand48, lrand48, and inrand48 store the last 48-bit X, generated 
in an internal buffer. Xj must be initialized prior to being invoked. The func- 
tions erand48, nrand48, and jrand48 require the calling program to provide 
storage for the successive X, values in the array specified as an argument when 
the fimctions are invoked. These routines do not have to be initialized; the cal- 
ling program must place the desired initial value of X; into the array and pass it 
as an argument. By using different arguments, functions erand48, nrand48, and 
jrand48 allow separate modules of a large program to generate several indepen- 
dent streams of pseudo-random numbers, i.e., the sequence of numbers in each 
stream will not depend upon how many times the routines have been called to 
generate numbers for the other streams. 

The initializer fimction srand48 sets the high-order 32 bits of X,- to the 32 bits 
contained in its argument. The low-order 16 bits of X,- are set to the arbitrary 
value 330Ei6. 

The initializer function seed48 sets the value of X^ to the 48-bit value specified in 
the argument array. In addition, the previous value of X^ is copied into a 48-bit 
internal buffer, used only by seed48, and a pointer to this buffer is the value 
returned by seed48. This returned pointer, which can just be ignored if not 
needed, is useful if a program is to be restarted from a given point at some future 
time — use the pointer to get at and store the last X, value, and then use this 
value to reinitialize via seed48 when the program is restarted. 

The initialization function lcong48 allows the user to specify the initial X,, the 
multiplier value a, and the addend value c. Argument array elements param[0'2] 
specify X,-, param[3-5] specify the multiplier a, and param[6] specifies the 16-bit 
addend c. After lcong48 has been called, a subsequent call to either srand48 or 
seed48 will restore the "standard" multiplier and addend values, a and c, 
specified on the previous page. 

SEE ALSO 

rand(3C). 
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NAME 

dup2 - duplicate an open file descriptor 

SYNOPSIS 

♦include <unistd.h> 

int dup2 (int f ildes, int £ildes2) ; 

DESCRIPTION 

fildes is a file descriptor referring to an open file, and fildesl is a non-negative 
integer less than {OPEN_MAX} (the maximum number of open files). dup2 causes 
fiJdesl to refer to the same file as fildes. If fttdesl already referred to an open file, 
not fildes, it is closed first. If fildesl refers to fildes, or if fildes is not a valid open 
file descriptor, fildesl will not be closed first. 

dup2 will fail if one or more of the following are true: 

EBADF fildes is not a valid open file descriptor. 

EBADF fildesl is negative or greater than or equal to {OPEN_MAX}. 

EINTR a signal was caught during the dup2 call. 

% [EMFILE {OPEN^MAX} file descriptors are currently open. 

SEE ALSO 

creat(2), close(2), exec(2), fcntl(2), open(2), pipe(2), lockf (3C), liinits(4). 
DIAGNOSTICS 

Upon successful completion a non-negative integer, namely, the file descriptor, is 
returned. Otherwise, a value of -1 is returned and errno is set to indicate the 
error. 
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NAME 

ecvt, f cvt, govt - convert floating-point number to string 

SYNOPSIS 

♦include <stdlib.h> 

char *ecvt (double value, int ndigit, int *decpt, int *sign) ; 
char ♦fcvt (double value, int ndigit, int *decpt, int *sign) ; 
char *gcvt (double value, int ndigit, char *buf ) ; 
DESCRIPTION 

ecvt converts value to a null-terminated string of ndigit digits and returns a 
pointer thereto. The high-order digit is non-zero, unless the value is zero. The 
low-order digit is rounded. The position of the decimal point relative to the 
beginning of the string is stored indirectly through decpt (negative means to the 
left of the returned digits). The decimal point is not included in the returned 
string. If the sign of the result is negative, the word pointed to by sign is non- 
zero, otherwise it is zero. 

fcvt is identical to ecvt, except that the correct digit has been rounded for 
printf %f output of the number of digits specified by ndigit. 

gcvt converts the value to a null-terminated string in the array pointed to by buf 
and returns buf. It attempts to produce ndigit significant digits in %f format if 
possible, otherwise %e format (scientific notation), ready for printing. A minus 
sign, if there is one, or a decimal point will be included as part of the returned 
string. Trailing zeros are suppressed. 

SEE ALSO 

printfOS). 

NOTES 

The values returned by ecvt and fcvt point to a single static data array whose 
content is overwritten by each call. 
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NAME 

end, etext, edata - last locations in program 

SYNOPSIS 

extern etext; 

extern edata; 

extern end; 

DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents; 
only their addresses are meaningftil. 

etext The address of etext is the first address above the program text. 

edata The address of edata is the first address above the initialized data region. 

end The address of end is the first address above the uninitialized data region. 

SEE ALSO 

cc(l), br)c(2), mallocOC), stdio(3S). 

NOTE 

When execution begins, the program break (the first location beyond the data) 
coincides with end, but the program break may be reset by the routines brk, mal- 
ice, the standard input /output library [see stdio(3S)], by the profile (-p) option 
of cc, and so on. Thus, the current value of the program break should be deter- 
mined by sbrk ((char *)0) [see brk(2)]. 
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NAME 

f close, f flush - close or flush a stream 

SYNOPSIS 

♦include <stdio.h> 

int fclose (FILE *stream) ; 
int ff lush (FILE *streaxn) ; 
DESCRIPTION 

fclose causes any buffered data waiting to be written for the named stream [see 
intro(3)] to be written out, and the stream to be closed. If the underlying file 
pointer is not already at end of file, and the file is one capable of seeking, the file 
pointer is adjusted so that the next operation on the open file pointer deals with 
the byte after the last one read from or written to the file being closed. 

fclose is performed automatically for all open files upon calling exit. 

If stream points to an output stream or an update stream on which the most 
recent operation was not input, f flush causes any buffered data waiting to be 
written for the named stream to be written to that file. Any unread data buffered 
in stream is discarded. The stream remains open. If stream is open for reading, 
the imderlying file pointer is not already at end of file, and the file is one capable 
of seeking, the file pointer is adjusted so that the next operation on the open file 
pointer deals with the byte after the last one read from or written to the stream. 

When calling f flush, if stream is a null pointer, all files open for writing are 
flushed. 

SEE ALSO 

close(2), exit(2), intro(3), fopenOS), setJ^ufOS), stdio(3S). 
DIAGNOSTICS 

Upon successful completion these functions return a value of zero. Otherwise EOF 
is returned. 



10/89 



Page 1 



terror (3S) 



terror (3S) 



NAME 

f error, f eof , clearerr, f ileno - stream status inquiries 

SYNOPSIS 

♦include <stdio.h> 

int f error (FILE * stream) ; 
int feof (FILE * stream); 
void clearerr (FILE * stream) / 
int f ileno (FILE '•'stream) ; 
DESCRIPTION 

f error returns non-zero when an error has previously occurred reading from or 
writing to the named stream [see introO)], otherwise zero. 

feof returns non-zero when EOF has previously been detected reading the named 
input stream, otherwise zero. 

clearerr resets the error indicator and EOF indicator to zero on the named 
stream. 

f ileno returns the integer file descriptor associated with the named stream; see 
open(2). 

SEE ALSO 

open(2), fopenOS), stdio(3S). 
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NAME 

f f s - find first set bit 

SYNOPSIS 

tinclude <strin9.h> 

int £f s (const int i) ; 
DESCRIPTION 

f f s finds the first bit set in the argument passed it and returns the index of that 
bit. Bits are numbered starting at 1 from the low order bit. A return value of 
zero indicates that the value passed is zero. 
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NAME 

fmtmsg - display a message on stderr or system console 

SYNOPSIS 

tinclude <ftntmsg.h> 

int fintmsgdong classification, const char *label, int severity, 
const char ^text, const char *action, const char *tag) ; 

DESCRIPTION 

Based on a message's classification component, fintmsg writes a formatted mes- 
sage to stderr, to the console, or to both. 

fmtmsg can be used instead of the traditional printf interface to display mes- 
sages to stderr. fmtmsg provides a simple interface for producing language- 
independent applications. 

A formatted message consists of up to five standard components as defined 
below. The component, classification, is not part of the standard message 
displayed to the user, but rather defines the source of the message and directs the 
display of the formatted message. 

classification 

Contains identifiers from the following groups of major classifications and 
subclassifications. Any one identifier from a subclass may be used in com- 
bination by ORing the values together with a single identifier from a dif- 
ferent subclass. Two or more identifiers from the same subclass should not 
be used together, with the exception of identifiers from the display sub- 
class. (Both display subclass identifiers may be used so that messages can 
be displayed to both stderr and the system console). 

"Major classifications" identify the source of the condition. Identifiers 
are: MdJIARD (hardware), JWjSOFT (software), and MMJFIRM (firmware). 

"Message source subclassifications" identify the type of software in 
which the problem is spotted. Identifiers are: MM_APPL (application), 
mjUTIL (utility), and WMjOPSYS (operating system). 

"Display subclassifications" indicate where the message is to be 
displayed. Identifiers are: MM_PRINT to display the message on the 
standard error stream, MljCX)NSOLE to display the message on the sys- 
tem console. Neither, either, or both identifiers may be used. 

"Status subclassifications" indicate whether the application will recover 
from the condition. Identifiers are: bWJE<EOOVER (recoverable) and 
M4_NREC0V (non-recoverable). 

An additional identifier, JfdJIOLIl^C, indicates that no classification 
component is supplied for the message. 

label Identifies the source of the message. The format of this component is two 
fields separated by a colon. The first field is up to 10 characters long; the 
second is up to 14 characters. Suggested usage is that label identifies the 
package in which the application resides as well as the program or applica- 
tion name. For example, the label UX:cat indicates the UNIX System V 
package and the cat application. 
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seventy 

Indicates the seriousness of the condition. Identifiers for the standard lev- 
els of severity are: 

MMJiALT indicates that the application has encountered a severe fault 
and is halting. Produces the print string HALT. 

bW^ERROR indicates that the application has detected a fault. Produces 
the print string ERROR. 

MMJIARNING indicates a condition out of the ordinary that might be a 
problem and should be watched. Produces the print string WARNING. 

^M_INFO provides information about a condition that is not in error. 
Produces the print string INFO. 

MIJJOSEV indicates that no severity level is supplied for the message. 

Other severity levels may be added by using the addseverity routine. 

text Describes the condition that produced the message. The text string is not 
limited to a specific size. 

action Describes the first step to be taken in the error recovery process, fmtmsg 
precedes each action string with the prefix: TO FIX:. The action string is 
not limited to a specific size. 

tag An identifier which references on-line documentation for the message. 
Suggested usage is that tag includes the label and a unique identifying 
number. A sample teg is UX : cat : 14 6. 

Environment Variables 

There are two environment variables that control the behavior of fmtmsg: 
MSGVERB and SEVJEVEL. 

MSGVERB tells fmtmsg which message components it is to select when writing 
messages to stderr. The value of MSGVERB is a colon-separated list of optional 
kejwords. MSGVERB can be set as follows: 

MSGVERB=[/^wwr(i[ : keywordl : ...]]] 
e:qport MSGVERB 

Valid keywords are: label, severity, text, action, and tag. If MSGVERB con- 
tains a keyword for a component and the component's value is not the 
component's null value, fmtmsg includes that component in the message when 
writing the message to stderr. If MSGVERB does not include a keyword for a 
message component, that component is not included in the display of the mes- 
sage. The keywords may appear in any order. If MSGVERB is not defined, if its 
value is the null-string, if its value is not of the correct format, or if it contains 
keywords other than the valid ones listed above, fmtmsg selects all components. 

The first time fmtmsg is called, it examines the MSGVERB environment variable to 
see which message components it is to select when generating a message to write 
to the standard error stream, stderr. The values accepted on the initial call are 
saved for future calls. 
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MSGfVERB affects only which components are selected for display to the standard 
error stream. All message components are included in console messages. 

SEV_LEVEL defines severity levels and associates print strings with them for use 
by fmtinsg. The standard severity levels shown below cannot be modified. Addi- 
tional severity levels can also be defined, redefined, and removed using 
addseverity [see addseverity(3C)]. If the same severity level is defined by 
both SEV^LEVEL and addseverity, the definition by addseverity is controlling. 

0 (no severity is used) 

1 HALT 

2 ERROR 

3 WARNING 

4 INFO 

SEV_LEVEL can be set as follows: 

SEV^lEVElMdescriptionl idescriptionl : ...]]] 
export SEVJJEVEL 

description is a comma-separated list containing three fields: 

description^'^severityjceyword, level, printstring 

seoerityjxyword is a character string that is used as the keyword on the -s seventy 
option to the fmtinsg command. (This field is not used by the fmtmsg function.) 

level is a character string that evaluates to a positive integer (other than 0, 1, 2, 3, 
or 4, which are reserved for the standard severity levels). If the keyword 
severity _key word is used, level is the severity value passed on to the f mt;msg func- 
tion. 

printstring is the character string used by fmtinsg in the standard message format 
whenever the severity value level is used. 

If a description in the colon list is not a three-field comma list, or, if the second 
field of a comma list does not evaluate to a positive integer, that description in the 
colon list is ignored. 

The first time fmtmsg is called, it examines the SEVJLEVEL environment variable, 
if defined, to see whether the environment expands the levels of severity beyond 
the five standard levels and those defined using addseverity. The values 
accepted on the initial call are saved for future calls. 

Use in Applications 

One or more message components may be systematically omitted from messages 
generated by an application by using the null value of the argument for that com- 
ponent. 

The table below indicates the null values and identifiers for fmtmsg arguments. 
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Argument Type 



Null-Value 



Identifier 



label char* 
severity int 



(char*) NULL 
0 



J«1_NULLLBL 

MdJTOLLSEV 

ifdJTOLLMC 

MMNOLLTXT 

bMNULLACT 

m NULLTAG 



class long 
text char* 
action char* 
tag char* 



OL 



(char*) NOLL 
(char*) NULL 
(char*) NULL 



Another means of systematically omitting a component is by omitting the com- 
ponent keyword(s) when defining the MSGfVERB environment variable (see the 
"Environment Variables" section). 



Example 1: 

The following example of frntmsg: 

fmtmsg (M4_PRINT, "UX:cat", mjERROR, "invalid syntax", "refer 
to manual", "UX: cat: 001") 

produces a complete message in the standard message format: 

UXicat: ERROR: invalid syntax 

TO FIX: refer to manual UX: cat: 001 

Example 2: 

When the environment variable MSGVERB is set as follows: 

MSGVERB=severity : text : action 

and the Example 1 is used, fmtmsg produces: 

ERROR: invalid syntax 
TO FIX: refer to manual 

Example 3: 

When the environment variable SEVJLEVEL is set as follows: 

SEy_LEVEL=note, 5, NOTE 

the following call to fmtmsg: 

fmtmsg (MMJJTIL I tM_PRINT, "UX:cat", 5, "invalid syntax", 
"refer to manual", "UX:cat :001") 



EXAMPLES 



produces: 



UX:cat: NOTE: invalid syntax 

TO FIX: refer to manual 



UX:cat:001 



SEE ALSO 



addseverity(3C), printf (3S). 
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DIAGNOSTICS 

The exit codes for fmtmsg are the following: 

MljOK The function succeeded. 
bf4_NOT0K The function failed completely. 

bfi_NOMSG The function was unable to generate a message on the standard 
error stream, but otherwise succeeded. 

M1_N0C0N The function was imable to generate a console message, but other- 
wise succeeded. 



10/89 



Page 5 



fopen(3S) 



fopen (3S) 



NAME 

fopen, f reopen, f dopen - open a stream 

SYNOPSIS 

♦include <stdio.h> 

FILE *£open (const char ^filename, const char *type) ; 

FILE '('freqpen (const char 't' filename ^ const char '''type, FILE 
♦stream) ; 

FILE *f dopen (int f ildes, const char *type) ; 
DESCRIPTION 

fopen opens the file named by filename and associates a stream with it. fopen 
returns a pointer to the FILE structure associated with the stream. 

filename points to a character string that contains the name of the file to be 
opened. 

type is a character string beginning with one of the following sequences: 
"r" or "rb" open for reading 

"w" or "wb" truncate to zero length or create for writing 

"a" or "ab" append; open for writing at end of file, or create for writing 

"r+", "r+b" or "rb+" 

open for update (reading and writing) 

"w+", "w+b" or "wb+" 

truncate or create for update 

"a+", "a+b" or "ab+" 

append; open or create for update at end-of-file 

The "b" is ignored in the above types. The "b" exists to distinguish binary files 
from text files. However, there is no distinction between these types of files on a 
UNIX system. 

f reopen substitutes the named file in place of the open stream. A flush is first 
attempted, and then the original stream is closed, regardless of whether the open 
ultimately succeeds. Failure to flush or close stream successfully is ignored, 
f reopen returns a pointer to the FILE structure associated with stream. 

f reopen is typically used to attach the preopened streams associated with stdin, 
stdout, and stderr to other files, stderr is by default unbuffered, but the use 
of f reopen will cause it to become buffered or line-buffered. 

f dopen associates a stream with a file descriptor. File descriptors are obtained 
from open, dup, creat, or pipe, which open files but do not return pointers to a 
FILE structure stream. Streams are necessary input for almost all of the Section 
3S library routines. The type of stream must agree with the mode of the open file. 
The file position indicator associated with stream is set to the position indicated 
by the file offset associated with fildes. 
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When a file is opened for update, both input and output may be done on the 
resulting stream. However, output may not be directly followed by input without 
an intervening f flusl\ fseek, fsetpos, or rewind, and input may not be 
directly followed by output without an intervening fseek, f setpos, or rewind, 
or an input operation that encounters end-of-file. 

When a file is opened for append (i.e., when type is "a", "ab", "a+", or "ab+")/ it 
is impossible to overwrite information already in the file, fseek may be used to 
reposition the file pointer to any position in the file, but when output is written 
to the file, the current file pointer is disregarded. All output is written at the end 
of the file and causes the file pointer to be repositioned at the end of the output. 
If two separate processes open the same file for append, each process may write 
freely to the file without fear of destroying output being written by the other. 
The output from the two processes will be intermixed in the file in the order in 
which it is written. 

When opened, a stream is fully buffered if and only if it can be determined not to 
refer to an interactive device. The error and end-of-file indicators are cleared for 
the stream. 

SEE ALSO 

close(2), cxeat(2), dup(2), open(2), pipe(2), write(2), fclose(3S), f seek(3S), 
setbuf (3S), stdioOS). 

DIAGNOSTICS 

The functions f open and f reopen return a null pointer if path cannot be accessed, 
or if type is invalid, or if the file cannot be opened. 

The function fdopen returns a null pointer if fildes is not an open file descriptor, 
or if type is invalid, or if the file cannot be opened. 

The functions f open or fdopen may fail and not set errno if there are no free 
stdio streams. 

File descriptors used by fdopen must be less than 255. 
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NAME 

fpgetround, fpsetround, fpgetnask, fpsetmask, fpgetsticky, fpsetsticky - 
IEEE floating-point environment control 

SYNOPSIS 

♦include <ieeefp.h> 

fp_rnd fpgetround (void) ; 
fp__rnd fpsetround (fp_rnd rnd_dir) ; 
fp__except fpgetinask (void) / 
fp_except Q>setinask (fpjexcept mask) ; 
fpjexcept Qpgetsticky (void) ; 
fp_jexcept ^set sticky (fpjexcept sticky) ; 
DESCRIPTION 

There are five floating-point exceptions: divide-by-zero, overflow, underflow, 
imprecise (inexact) resiilt, and invalid operation. When a floating-paint exception 
occurs, the corresponding sticky bit is set (1), and if the mask bit is enabled (1), 
the trap takes place. These routines let the user change the behavior on 
occurrence of any of these exceptions, as well as change the rounding mode for 



floating-point operations. 




FP X INV 


/* invalid operation exception */ 


FP X OFL 


/* overflow exception */ 


FP X UFL 


/* underflow exception */ 


FP X DZ 


/♦ divide-by-zero exception */ 


FP X IMP 


/* iitprecise (loss of precision) */ 


FP RN 


/* round to nearest representative nuiriber */ 


FP RP 


/* round to plus infinity */ 


FP RM 


/* round to minus infinity */ 


FP RZ 


/* round to zero (truncate) */ 



fpgetround returns the current rounding mode. 

fpsetround sets the rounding mode and returns the previous rounding mode, 
fpgetiinask returns the current exception masks, 
fpsetmask sets the exception masks and returns the previous setting, 
fpgetsticky returns the current exception sticky flags. 

fpsetsticky sets (clears) the exception sticky flags and returns the previous set- 
ting. 

The default environment is rounding mode set to nearest (FP_RN) and all traps 
disabled. 

Individual bits may be examined using the constants defined in ieeefp.h. 

SEE ALSO 

isnan(3C). 
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NOTES 

fpsetsticky modifies all sticky flags, fpsetmask changes all mask bits, fpset- 
znask clears the sticky bit corresponding to any exception being enabled. 

C requires tnincation (round to zero) for floating point to integral conversions. 
The current rounding mode has no effiect on these conversions. 

One must clear the sticky bit to recover from the trap and to proceed. If the 
sticky bit is not cleared before the next trap occurs, a wrong exception type may 
be signaled. 
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NAME 

f read, fwrite - binary input/output 

SYNOPSIS 

♦include <stdio.h> 

sizejt fread (void *ptr, size__t size^ size_t nitems, FILE * stream) ; 

sizejt fwrite (const void *ptr, size_t size, size_t nitems, FILE 
* stream) ; 

DESCRIPTION 

fread reads into an array pointed to by ptr up to nitems items of data from 
stream, where an item of data is a sequence of bytes (not necessarily terminated 
by a null byte) of length size, fread stops reading bytes if an end-of-file or error 
condition is encountered while reading stream, or if nitems items have been read, 
fread increments the data pointer in stream to point to the byte following the last 
byte read if there is one. fread does not change the contents of stream, fread 
returns the number of items read. 

fwrite writes to the named output stream at most nitems items of data from the 
array pointed to by ptr, where an item of data is a sequence of bytes (not neces- 
sarily terminated by a null byte) of length size, fwrite stops writing when it has 
written nitems items of data or if an error condition is encoimtered on stream. 
fwrite does not change the contents of the array pointed to by ptr. fwrite 
increments the data-pointer in stream by the number of bytes written, fwrite 
returns the number of items written. 

If size or nitems is zero, then fread and fwrite return a value of 0 and do not 
effect the state of stream. 

The f error or f eof routines must be used to distinguish between an error condi- 
tion and end-of-file condition. 

SEE ALSO 

exit(2), lseek(2), read(2), write(2), abort(3C), f close(3S), f open(3S), getc(3S), 
gets(3S), printf (3S), putc(3S), puts(3S), scanf (3S), stdio(3S). 

DIAGNOSTICS 

If an error occurs, the error indicator for stream is set. 
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NAME 

frexp, Idexp, logb, modf, modf f, nextafter, scalb - manipulate parts of 
floating-point numbers 

SYNOPSIS 

♦include <inath.h> 

double fre^ (double value, int *eptr) ; 
double Idexp (double value, int exp) ; 
double logb (double value) ; 

double nextafter (double value 1, double value2); 
double scalb (double value, double exp) ; 
double xnodf (double value, double *iptr) ; 
float modff (float value, float *iptr); 
DESCRIPTION 

Every non-zero number can be written uniquely as jc * 2", where the "mantissa" 
(fraction) x is in the range 0.5 < \ x \ < 1.0, and the "exponent" n is an integer, 
f rexp returns the mantissa of a double value, and stores the exponent indirectly 
in the location pointed to by eptr. If value is zero, both results returned by frexp 
are zero. 

Idexp and scalb return the quantity value * 2^. The only difference between 
the two is that scalb of a signaling NaN will result in the invalid operation 
exception being raised. 

logb returns the unbiased exponent of its floating-point argument as a double- 
precision floating-point value. 

modf and modff (single-precision version) return the signed fractional part of 
value and store the integral part indirectly in the location pointed to by iptr. 

nextafter returns the next representable double-precision floating-point value 
following valuel in the direction of value! . Thus, if value! is less than valuel, 
nextafter returns the largest representable floating-point number less than 
valuel. 

SEE ALSO 

cc(l), introOM). 

DIAGNOSTICS 

If 16&yo£t would cause overflow, ±HUGE (defined in inath.h) is returned (according 
to the sign of value), and errno is set to ERANGE. If Idexp would cause 
underflow, zero is returned and errno is set to ERANGE. If the input value to 
Idexp is NaN or infinity, that input is returned and errno is set to EDOM. The 
same error conditions apply to scalb except that a signaling NaN as input will 
result in the raising of the invalid operation exception. 

logb of NaN returns that NaN, logb of infinity returns positive infinity, and 
logb of zero returns negative infinity and results in the raising of the divide by 
zero exception. In each of these conditions errno is set to EDOM. 
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If input valuel to nextaf ter is positive or negative infinity, that input is returned 
and errno is set to EDOM. The overflow and inexact exceptions are signalled 
when input valuel is finite, but nextaf ter (valuel , value!) is not. The underflow 
and inexact exceptions are signalled when nextaf ter (i;a/Me2 , value!) lies strictly 
between ±2 .In both cases errno is set to ERAN6E. 

When the program is compiled with the cc options -Xc or -Xa, HUGE_VAL is 
returned instead of HUGE . 
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NAME 

f seek; rewind, ftell - reposition a file pointer in a stream 

SYNOPSIS 

finclude <8tdio.h> 

int fseek (FILE *stream, long offset, int ptrname) ; 
void rewind (FILE '•'Stream) ; 
long ftell (FILE * stream) ; 
DESCRIPTION 

fseek sets the position of the next input or output operation on the stream [see 
intro(3)]. The new position is at the signed distance offset bytes from the begin- 
ning, from the current position, or from the end of the file, according to a ptrname 
value of SEEK_SET, SEEKJCUR, or SEEK_END (defined in stdio.h) as follows: 

SEEKjSET set position equal to offset bytes. 

SEEKJCUR set position to current location plus offset, 

SEEK_END set position to EOF plus offset. 

fseek allows the file position indicator to be set beyond the end of the existing 
data in the file. If data is later written at this point, subsequent reads of data in 
the gap will return zero until data is actually written into the gap. fseek, by 
itself, does not extend the size of the file. 

rewind (stream) is equivalent to: 

(void) fseek (stream, OL, SEEK__SET) ; 

except that rewind also clears the error indicator on stream. 

fseek and rewind clear the EOF indicator and undo any effects of ungetc on 
stream. After fseek or rewind^ the next operation on a file opened for update 
may be either input or output. 

If stream is writable and buffered data has not been written to the underlying file, 
fseek and rewind cause the unwritten data to be written to the file. 

ftell returns the offset of the current byte relative to the beginning of the file 
associated with the named stream. 

SEE ALSO 

lseek(2), write(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S). 
DIAGNOSTICS 

fseek returns -1 for improper seeks, otherwise zero. An improper seek can be, 
for example, an fseek done on a file that has not been opened via f open; in par- 
ticular, fseek may not be used on a terminal or on a file opened via popen. 
After a stream is closed, no further operations are defined on that stream. 

NOTES 

Although on the UNIX system an offset returned by ftell is measured in bytes, 
and it is permissible to seek to positions relative to that offset, portability to non- 
UNIX systems requires that an offset be used by fseek directly. Arithmetic may 
not meaningfully be performed on such an offset, which is not necessarily meas- 
ured in bytes. 
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NAME 

£setpos, f getpos ~ reposition a file pointer in a stream 

SYNOPSIS 

♦include <stdio.h> 

int fsetpos (FILE * stream, const fpos_t ♦pes) ; 
int f getpos (FILE * stream, fpos_t *pos) ; 
DESCRIPTION 

fsetpos sets the position of the next input or output operation on the stream 
according to the value of the object pointed to by pos. The object pointed to by 
pos must be a value returned by an earlier call to f getpos on the same stream. 

fsetpos clears the end-of-file indicator for the stream and imdoes any effects of 
the ungetc fimction on the same stream. After fsetpos, the next operation on a 
file opened for update may be either input or output. 

f getpos stores the current value of the file position indicator for stream in the 
object pointed to by pos. The value stored contains information usable by fset- 
pos for repositioning the stream to its position at the time of the call to f getpos. 

If successful, both fsetpos and f getpos return zero. Otherwise, they both return 
nonzero. 

SEE ALSO 

f seekOS), lseek(2) ungetc(3S). 
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NAME 

f tw - walk a file tree 

SYNOPSIS 

♦include <ftw.h> 

int ftw (const char *path, int (*fn) (const char *, const struct 
Stat * , int) , int depth) ; 

DESCRIPTION 

ftw recursively descends the directory hierarchy rooted in path. For each object 
in the hierarchy, ftw calls the user-defined function fn, passing it a pointer to a 
null-terminated character string containing the name of the object, a pointer to a 
Stat structure (see stat(2)) containing information about the object, and an 
integer. Possible values of the integer, defined in the <ftw.h> header file, are: 

FTWUF The object is a file. 

FTW_D The object is a directory. 

FTW_pNR The object is a directory that cannot be read. Descendants of the 
directory will not be processed. 

FTW_NS Stat failed on the object because of lack of appropriate permission 
or the object is a symbolic link that points to a non-existent file. The 
Stat buffer passed to fn is undefined. 

ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an invocation of fn returns 
a nonzero value, or some error is detected within ftw (such as an I/O error). If 
the tree is exhausted, ftw returns zero. If fn returns a nonzero value, ftw stops 
its tree traversal and returns whatever value was returned by fn. If ftw detects 
ah error other than EACCES, it returns -1, and sets the error type in ermo. 

ftw uses one file descriptor for each level in the tree. The depth argument limits 
the number of file descriptors so used. If depth is zero or negative, the effect is 
the same as if it were 1. depth must not be greater than the number of file 
descriptors currently available for use. ftw will run more quickly if depth is at 
least as large as the number of levels in the tree. When ftw returns it closes any 
file descriptors which it has opened. It does not close any file descriptors which 
may have been opened by fn, 

SEE ALSO 

stat(2), mallocOC). 

NOTES 

Because ftw is recursive, it is possible for it to terminate with a memory fault 
when applied to very deep file structures. 

ftw uses mallocOC) to allocate dynamic storage during its operation. If ftw is 
forcibly terminated, such as by long jirp being executed by fn or an interrupt rou- 
tine, ftw will not have a chance to free that storage, so it will remain per- 
manently allocated. A safe way to handle interrupts is to store the fact that an 
interrupt has occurred, and arrange to have fn return a nonzero value at its next 
invocation. 
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NAME 

getc, getchar, f getc, getw - get character or word from a stream 

SYNOPSIS 

♦include <stdio.h> 

int getc (FILE * stream); 
int getchar (void) ; 
int fgetc (FILE *stream) ; 
int getw (FILE stream); 
DESCRIPTION 

getc returns the next character (i.e., byte) from the named input stream [see 
intro(3)] as an unsigned char converted to an int. It also moves the file 
pointer, if defined, ahead one character in stream, getchar is defined as 
getc (stdin) . getc and getchar are macros. 

fgetc behaves like getc, but is a function rather than a macro, fgetc runs more 
slowly than getc, but it takes less space per invocation and its name can be 
passed as an argument to a fimction. 

getw returns the next word (i.e., integer) from the named input stream, getw 
increments the associated file pointer, if defined, to point to the next word. The 
size of a word is the size of an integer and varies from machine to machine, 
getw assumes no special alignment in the file. 

SEE ALSO 

fcloseOS), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), scanf(3S), 
stdio(3S), ungetc(3S). 

DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an error and set the 
EOF or error indicator of stream, respectively. Because EOF is a valid integer, f er- 
ror should be used to detect getw errors. 

NOTES 

If the integer value returned by getc, getchar, or fgetc is stored into a charac- 
ter variable and then compared against the integer constant EOF, the comparison 
may never succeed, because sign-extension of a character on widening to integer 
is implementation dependent. 

The macro version of getc evaluates a stream argument more than once and may 
treat side effects incorrectly. In particular, getc(*f++) does not work sensibly. 
Use fgetc instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are implementation dependent, and may not be read using getw on a 
different processor. 

Functions exist for all the above-defined macros. To get the function form, the 
macro name must be undefined (e.g., #undef getc). 



10/89 



Page 1 



getcwd (3C) 



getcwd(3C) 



NAME 

getcwd - get pathname of current working directory 

SYNOPSIS 

♦include <unistd.h> 

char *getcwd (char *buf , int size) ; 

DESCRIPTION 

getcwd returns a pointer to the current directory pathname. The value of size 
must be at least one greater than the length of the pathname to be returned. 

If buf is not NULL, the pathname will be stored in the space pointed to by buf. 

If buf is a NULL pointer, getcwd will obtain size bytes of space using xnalloc(3C). 
In this case, the pointer returned by getcwd may be used as the argument in a 
subsequent call to free. 

getcwd will fail if one or more of the following are true: 
EACCES A parent directory cannot be read to get its name. 
EINVAL size is equal to 0. 

ERANGE size is less than 0 or is greater than 0 and less than the length of the 
pathname plus 1. 

EXAMPLE 

Here is a program that prints the current working directory. 

♦include <unistd.h> 
♦include <stdio.h> 

xnainO 
{ 

char *cwd; 

if ((cwd = getcwd (NULL, 64)) — NULL) 
{ 

perror ("pwd") ; 
exit (2) ; 

} 

(void)printf ("%s\n", cwd) ; 
return (0) / 

} 

SEE ALSO 

malloc(3C) 

DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an error occurs in a 
lower-level function. 
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NAME 

getenv - return value for environment name 

SYNOPSIS 

♦include <stdlib.h> 

char *getenv (const char *naine) ; 

DESCRIPTION 

getenv searches the environment list [see environ(5)] for a string of the form 
name=value and, if the string is present, returns a pointer to the value in the 
current environment. Otherwise, it returns a null pointer. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 
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NAME 

getgrent, getgrgid^ getgrnam, setgrent, endgrent, f getgrent - get group 
file entry 

SYNOPSIS 

♦include <grp.h> 

struct grov?) * getgrent (void) ; 
struct groi:^) *getgrgid (gid_t gid) ; 
struct groi:?) *getgrnain (const char *naine) ; 
void setgrent (void) ; 
void endgrent (void) ; 
struct groiq? *f getgrent (FIIE *f ) ; 
DESCRIPTION 

getgrent, getgrgid, and getgrnam each return pointers to an object containing 
the broken-out fields of a line in the /etc/group file. Each line contains a 
"group" structure, defined in the grp.h header file with the following members: 

char *gr_naine; /* the name of the group */ 

char *grjpasswd; /* the encrypted group password */ 

gidjt gr_jgid; /* the nianerical groi^) ID */ 

char **gr_mem; /* vector of pointers to member names */ 

When first called, getgrent returns a pointer to the first group structure in the 
file; thereafter, it returns a pointer to the next group structure in the file; so, suc- 
cessive calls may be used to search the entire file, getgrgid searches from the 
beginning of the file until a numerical group id matching gid is found and returns 
a pointer to the particular structure in which it was found. 

getgrnam searches from the beginning of the file until a group name matching 
name is found and returns a pointer to the particular structure in which it was 
found. If an end-of-file or an error is encountered on reading, these functions 
return a null pointer. 

A call to setgrent has the effect of rewinding the group file to allow repeated 
searches, endgrent may be called to close the group file when processing is 
complete. 

f getgrent returns a pointer to the next group structure in the stream /, which 
matches the format of /etc/group. 

FILES 

/etc/group 

SEE ALSO 

getlogin(3C), getpwentOC). 

group(4) in the System Administrator's Reference Manual 
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DIAGNOSTICS 

getgrent, getgrgid, getgrnam, and f getgrent return a null pointer on EOF or 
error. 

NOTES 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

getlogin - get login name 

SYNOPSIS 

♦include <stdlib.h> 

char * getlogin (void) ; 
DESCRIPTION 

getlogin returns a pointer to the login name as found in /etc/utmp. It may be 
used in conjunction with getpwnam to locate the correct password file entry when 
the same user ID is shared by several login names. 

If getlogin is called within a process that is not attached to a terminal, it returns 
a NULL pointer. The correct procedure for determining the login name is to call 
cuserid, or to call getlogin and if it fails to call getpwuid. 

FILES 

/etc/utnp 
SEE ALSO 

cuserid(3S), getgrent(3C), getpwent(3C), utirp(4). 
DIAGNOSTICS 

Returns the NULL pointer if the login name is not found. 

NOTES 

The return values point to static data whose content is overwritten by each call. 
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NAME 

getinntent, getmntany - get mnttab file entry 

SYNOPSIS 

♦include <stdio.h> 
♦include <sys/innttab.h> 

int getmntent (FILE *£p, struct mnttab '•'np) ; 

int getmntany (FILE *£p, struct mnttab *irp, struct mnttab *nipref); 
DESCRIPTION 

getmntent and getunntcuiy each fill in the structure pointed to by mp with the 
broken-out fields of a line in the /etc/mnttab file. Each line in the file contains 
a mnttab structure, declared in the sys/ronttab.h header file: 

struct mnttab { 

char *rontjspecial; 
char *mnt_inountp; 
char *mnt_fstype; 
char ♦mnt_mntqpts; 
char *mntjtime; 

}; 

The fields have meanings described in mnttab(4). 

getmntent returns a pointer to the next mnttab structure in the file; so successive 
calls can be used to search the entire file, getmntany searches the file referenced 
by fp until a match is found between a line in the file and mpref. mpref matches 
the line if all non-null entries in mpref match the corresponding fields in the file. 
Note that these routines do not open, close, or rewind the file. 

FILES 

/etc/mnttab 

SEE ALSO 

mnttab(4). 

DIAGNOSTICS 

If the next entry is successfully read by getmntent or a match is found with 
getmntany, 0 is returned. If an end-of-file is encountered on reading, these fimc- 
tions return -1. If an error is encountered, a value greater than 0 is returned. 
The possible error values are: 

MNTJTOOIONG A line in the file exceeded the internal buffer size of 

MNTJilNEJlAX. 

MNT_JIXX»1ANY A line in the file contains too many fields. 

MNTjrCXDFEW A line in the file contains too few fields. 

NOTES 

The members of the mnttab structure point to information contained in a static 
area, so it must be copied if it is to be saved. 
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NAME 

getopt - get option letter from argument vector 

SYNOPSIS 

finclude <stdlib.h> 

int getopt (int argc, char * const *argv^ const char *optstring) ; 
extern char ♦optarg; 
extern int optind, opterr, optopt; 
DESCRIPTION 

getopt returns the next option letter in argv that matches a letter in optstring. It 
supports all the rules of the command syntax standard [see intro(l)]. Since all 
new commands are intended to adhere to the command s)mtax standard, they 
should use getopts(l), getopt (3C), or getsubopts(3C) to parse positional 
parameters and check for options that are legal for that command. 

optstring must contain the option letters the command using getopt will recog- 
nize; if a letter is followed by a colon, the option is expected to have an argu- 
ment, or group of arguments, which may be separated from it by white space. 
optarg is set to point to the start of the option argument on return from getopt. 

getopt places in optind the argv index of the next argument to be processed. 
optind is external and is initialized to 1 before the first call to getopt. When all 
options have been processed (i.e., up to the first non-option argument), getopt 
returns EOF. The special option " — " (two hyphens) may be used to delimit the 
end of the options; when it is encountered, EOF is returned and " — " is skipped. 
This is useful in delimiting non-option arguments that begin with (hyphen). 

EXAMPLE 

The following code fragment shows how one might process the arguments for a 
command that can take the mutually exclusive options a and b, and the option o, 
which requires an argument: 

♦include <stdlib.h> 
♦include <stdio.h> 

main (int argc, char ♦*argv) 
{ 

int c; 

extern char * optarg; 
extern int optind; 
int aflg = 0; 
int bflg = 0; 
int err fig =0; 
char *ofile = NULL; 

while ((c = getopt (argc, argv, "abo:")) != EOF) 
switch (c) { 
case 'a' : 

if (bflg) 

errflg++; 
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else 

aflg+-+; 
break; 
case 'b' : 

if (aflg) 

errflg++; 

else 

bflg++; 
break; 
case 'o' : 

ofile = optarg; 

(void)printf ("ofile = %s\n"r ofile); 
break; 
case ' ?' : 

errflg++; 

} 

if (errflg) { 

(void) fprintf (stderrr 

"usage: cmd [-a|-b] [-o<file>] files. . An") ; 
exit (2) ; 

} 

for ( ; optind < argc; optind++) 

(void)printf ("%s\n", argv[pptind] ) ; 
return 0; 

} 

SEE ALSO 

get suboptOO . 

getopts(l), intro(l) in the User's Reference Manual 
DIAGNOSTICS 

getcpt prints an error message on the standard error and returns a (ques- 
tion mark) when it encounters an option letter not included in optstring or no 
argument after an option that expects one. This error message may be disabled 
by setting ppterr to 0. The value of the character that caused the error is in 
optcpt. 

NOTES 

The library routine getopt does not fully check for mandatory arguments. That 
is, given an option string a:b and the input -a -b, getopt assumes that -b is the 
mandatory argument to the option -a and not that -a is missing a mandatory 
argument. 

It is a violation of the command syntax standard [see intro(l)] for options with 
arguments to be grouped with other options, as in cmd -aboxxx file, where a 
and b are options, o is an option that requires an argument, and xxx is the argu- 
ment to o. Although this syntax is permitted in the current implementation, it 
should not be used because it may not be supported in future releases. The 
correct syntax is cmd -ab -oxxx file. 
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NAME 

getpass - read a password 

SYNOPSIS 

♦include <stdlib.h> 

char * getpass (const char '''prompt) ; 
DESCRIPTION 

getpass reads up to a newline or EOF from the file /dev/tty, after prompting on 
the standard error output with the null-terminated string prompt and disabling 
echoing. A pointer is returned to a null-terminated string of at most 8 characters. 
If /dev/tty cannot be opened, a null pointer is returned. An interrupt will ter- 
minate input and send an interrupt signal to the calling program before return- 
ing. 

FILES 

/dev/tty 

NOTE 

The return value points to static data whose content is overwritten by each call. 
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NAME 

getpw - get name from UID 

SYNOPSIS 

♦include <stdlib.h> 

int getpw (uid_t uid, char *buf ) ; 
DESCRIPTION 

getpw searches the password file for a user id number that equals uid, copies the 
line of the password file in which uid was found into the array pointed to by buf, 
and returns 0. getpw returns non-zero if uid cannot be found. 

This routine is included only for compatibility with prior systems and should not 
be used; see getpwent(3C) for routines to use instead. 

FILES 

/etc/passwd 

SEE ALSO 

getpwent(3C). 

passwd(4) in the System Administrator's Reference Manual 

DIAGNOSTICS 

getpw returns non-zero on error. 
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NAME 

getpwent, getpwuid, getpwnaitv setpwent, enc^went, f getpwent - manipulate 
password file entry 

SYNOPSIS 

♦include <pwd.h> 

struct passwd *getpwent (void) ; 
struct passwd *getpwuid (uidjt uid); 
struct passwd *getpwnain (const char *naxne) ; 
void setpwent (void) ; 
void endpwent (void) ; 
struct passwd '•'fgetpwent (FILE *£) ; 
DESCRIPTION 

getpwent, getpwuid, and getpwnam each returns a pointer to an object with the 
following structure containing the broken-out fields of a line in the / etc/pas swd 
file. Each line in the file contains a passwd structure, declared in the pwd.h 
header file: 

struct passwd { 

char *pwjna2ne; 
char ♦pw_j>asswd; 
uid^t pw_uid; 
gid__t pw_gid; 
char ♦pw_age; 
char *pw_conTOent; 
char *pw__gecos; 
char *pwjdir; 
char *pw_shell; 

}; 

getpwent when first called returns a pointer to the first passwd structure in the 
file; thereafter, it returns a pointer to the next passwd structure in the file; so suc- 
cessive calls can be used to search the entire file, getpwuid searches from the 
beginning of the file until a numerical user id matching uid is foimd and returns 
a pointer to the particular structure in which it was found, getpwnam searches 
from the beginning of the file until a login name matching name is found, and 
returns a pointer to the particular structure in which it was found. If an end-of- 
file or an error is encountered on reading, these functions return a null pointer. 

A call to setpwent has the effect of rewinding the password file to allow 
repeated searches, endpwent may be called to close the password file when pro- 
cessing is complete. 

f getpwent returns a pointer to the next passwd structure in the stream /, which 
matches the format of /etc/passwd. 

FILES 

/etc/passwd 
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SEE ALSO 

getloginOO, getgrent(3C). 

passwd(4) in the System Administrator's Reference Manual. 
DIAGNOSTICS 

getpwent/ getpwnid, getpwnanv and fgetpwent return a null pointer on EOF or 
error. 

NOTES 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

gets, f gets - get a string from a stream 

SYNOPSIS 

♦include <stdio.h> 

char *gets (char *s) ; 

char *fgets (char *s, int n, FILE * stream) ; 
DESCRIPTION 

gets reads characters from the standard input stream [see intro(3)], stdin, into 
the array pointed to by s, until a newline character is read or an end-of-file condi- 
tion is encountered. The newline character is discarded and the string is ter- 
minated with a null character. 

fgets reads characters from the stream into the array pointed to by s, until n-1 
characters are read, or a newline character is read and transferred to s, or an 
end-of-file condition is encountered. The string is then terminated with a null 
character. 

When using gets, if the length of an input line exceeds the size of s, indeter- 
minate behavior may result. For this reason, it is strongly recommended that 
gets be avoided in favor of fgets. 

SEE ALSO 

lseek(2), read(2), ferror(3S), fopen(3S), fread(3S), getc(3S), scanf(3S), 
stdio(3S), ungetc(3S). 

DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no characters are 
transferred to s and a null pointer is returned. If a read error occurs, such as try- 
ing to use these functions on a file that has not been opened for reading, a null 
pointer is returned and the error indicator for the stream is set. If end-of-file is 
encountered, the EOF indicator for the stream is set. Otherwise s is returned. 
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NAME 

getsubopt - parse suboptions from a string 

SYNOPSIS 

♦include <stdlib.h> 

int getsubopt (char ♦*cptionp, char * const *tokens, char **valuep)/ 
DESCRIPTION 

getsubopt parses suboptions in a flag argument that was initially parsed by 
getopt. These suboptions are separated by commas and may consist of either a 
single token or a token-value pair separated by an equal sign. Since commas 
delimit suboptions in the option string, they are not allowed to be part of the 
suboption or the value of a suboption. A command that uses this syntax is 
nount(lM), which allows the user to specify mount parameters with the -o 
option as follows: 

mount -o rw,hard,bg,wsize«1024 speed :/usr /usr 

In this example there are four suboptions: rw, hard, bg, and wsize, the last of 
which has an associated value of 1024. 

getsubopt takes the address of a pointer to the option string, a vector of possible 
tokens, and the address of a value string pointer. It returns the index of the 
token that matched the suboption in the input string or -1 if there was no match. 
If the option string at optionp contains only one subobtion, getsubopt updates 
optionp to point to the null character at the end of the string; otherwise it isolates 
the suboption by replacing the comma separator with a null character, and 
updates optionp to point to the start of the next suboption. If the suboption has 
an associated value, getsubopt updates valuep to point to the value's first charac- 
ter. Otherwise it sets valuep to NULL. 

The token vector is organized as a series of pointers to null strings. The end of 
the token vector is identified by a null pointer. 

When getsubopt returns, if valuep is not NULL, then the suboption processed 
included a value. The calling program may use this information to determine if 
the presence or lack of a value for this subobtion is an error. 

Additionally, when getsubopt fails to match the suboption with the tokens in 
the tokens array, the calling program should decide if this is an error, or if the 
unrecognized option should be passed to another program. 

EXAMPLE 

The following code fragment shows how to process options to the mount com- 
mand using getsubopt. 

♦include <stdlib.h> 

char *iiiyopts[] = { 
♦define READONLY 0 
"ro", 

♦define READWRITE 1 
"rw", 
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tdefine WRITESIZE 



B 2 
"wsize", 
3 



tdefine READSIZE 



"rsize"r 
NULL}; 



xnain(argc, argv) 
int argc; 
dfciar **argv; 

{ 



int sc^ c, errflag; 
char * opt ions, * value; 
extern char *optarg; 
extern int pptind; 



while ((c = getopt(argc, argv, "abf:o:")) != -1) { 
switch (c) { 

case 'a' : /* process a option */ 
break; 

case 'b' : /* process b option */ 

break; 
case 'f ' : 

of ile = optarg; 
break; 
case ' ? ' : 

errflag++; 
break; 
case 'o' : 

options = optarg; 

while (*options != '\0') { 

switch (getsiabopt ( &opt ions , ityopt s , fivalue ) { 
case READONLY : /* process ro option */ 
break; 

case READWRITE : /* process rw option */ 
break; 

case WRITESIZE : /* process wsize option */ 



if (value = NULL) { 

error_no_arg ( ) ; 

errflag++; 
} else 

write_size = atoi (value) ; 
break; 

case READSIZE : /* process rsize option */ 
if (value = NULL) { 

error_no_jarg ( ) ; 

errflag++; 
} else 
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readj3ize = atoi (value); 
break; 
default : 

/♦ process unknown token */ 
error Jbad^token (value) ; 
errflag++; 
break; 

} 

} 

break; 

} 

} 

if (errflag) { 

/* print usage instructions etc. */ 

} 

for (; optind<argc; optind++) { 

/* process remaining arguments */ 

} 



} 

SEE ALSO 

getopt(3C). 

DIAGNOSTICS 

getsubqpt returns -1 when the token it is scanning is not in the token vector. 
The variable addressed by valuep contains a pointer to the first character of the 
token that was not recognized rather than a pointer to a value for that token. 

The variable addressed by optionp points to the next option to be parsed, or a null 
character if there are no more options. 

NOTES 

During parsing, commas in the option input string are changed to null characters. 
White space in tokens or token-value pairs must be protected from the shell by 
quotes. 
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NAME 

getut: getutent, getutid, getutline^ pututline, setutent, endutent, utitp- 
name - access utmp file entry 

SYNOPSIS 

♦include <utirp.h> 

struct utirp ♦getutent (void) ; 
struct utmp '•'getut id (const struct utmp '•'id) ; 
struct utxip *getutline (const struct utnp *line) ; 
struct utxtp ♦pututline (const struct utirp *utirp) ; 
void setutent (void) ; 
void endutent (void) ; 
int utnpname (const char *£ile) ; 
DESCRIPTION 

getutent, getutid, getutline, and pututline each return a pointer to a struc- 
ture with the following members: 

char utjuser[8]; /* User login name */ 

char ut_id[4]; /* /etc/inittab id (usually line #) */ 

char ut_line[12]; /* device name (console, Inxx) */ 

short ut_pid; /* process id */ 

short ut_type; /* type of entry */ 

struct exitjstatus { 

} utjexit; /* The exit status of a process 

/* marked as DEAD_PROCESS . */ 
tixne_t ut_time; /* time entry was made */ 

The structure exitjstatus includes the following members: 

short extermination; /* Process termination status */ 
short e_exit; /* Process exit status */ 

getutent reads in the next entry from a utuip-like file. If the file is not already 
open, it opens it. If it reaches the end of the file, it fails. 

getutid searches forward from the current point in the utxap file until it finds an 
entry with a utjype matching id'>utjype if the type specified is RUN__LVL, 
BOOTjriME, OLDjriME or NEWJTIME. If the type specified in id is INITJPROCESS, 
LOGIN_PROCESS, USER_PROCESS or DEAD_PRCX:ess, then getutid will return a 
pointer to the first entry whose type is one of these four and whose ut__id field 
matches id'>ut jd. If the end of file is reached without a match, it fails. 

getutline searches forward from the current point in the utmp file until it finds 
an entry of the type LOGIN_PROCESS or USERJPROCESS that also has a utjine 
string matching the line->MMzn^ string. If the end of file is reached without a 
match, it fails. 



10/89 



Page 1 



getut(3C) 



getut(3C) 



pututline writes out the supplied utnp structure into the utirp file. It uses 
getutid to search forward for the proper place if it finds that it is not already at 
the proper place. It is expected that normally the user of pututline will have 
searched for the proper entry using one of the getut routines. If so, pututline 
will not search. If pututline does not find a matching slot for the new entry, it 
will add a new entry to the end of the file. It returns a pointer to the utnp struc- 
ture. 

setutent resets the input stream to the beginning of the file. This reset should 
be done before each search for a new entry if it is desired that the entire file be 
examined. 

endutent closes the currently open file. 

utxrpname allows the user to change the name of the file examined, from 
/etc/ut:inp to any other file. It is most often expected that this other file will be 
/etc/wtirp. If the file does not exist, this will not be apparent until the first 
attempt to reference the file is made, utirpname does not open the file. It just 
closes the old file if it is currently open and saves the new file name. If the file 
name given is longer than 79 characters, utirpname returns 0. Otherwise, it will 
return 1. 

FILES 

/etc/utirp 
/etc/wtirp 

SEE ALSO 

ttyslotOC), utirp(4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for permissions or hav- 
ing reached the end of file, or upon failure to write. 

NOTES 

The most current entry is saved in a static structure. Multiple accesses require 
that it be copied before further accesses are made. On each call to either getutid 
or getut line, the routine examines the static structure before performing more 
I/O. If the contents of the static structure match what it is searching for, it looks 
no further. For this reason, to use getutline to search for multiple occurrences, 
it would be necessary to zero out the static area after each success, or getutline 
would just return the same structure over and over again. There is one exception 
to the rule about emptying the structure before further reads are done. The 
implicit read done by pututline (if it finds that it is not already at the correct 
place in the file) will not hurt the contents of the static structure returned by the 
getutent, getutid or getutline routines, if the user has just modified those 
contents and passed the pointer back to pututline. 

These routines use buffered standard I/O for input, but pututline uses an 
unbuffered non-standard write to avoid race conditions between processes trying 
to modify the ut:np and wtirp files. 
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NAME 

hsearch, hcreate, hdestroy - manage hash search tables 

SYNOPSIS 

finclude <search.h> 

ENTRY *hsearch (ENTRY item, ACTION action) ; 
int hcreate (size_t nel) ; 
void hdestroy (void) ; 
DESCRIPTION 

hsearch is a hash-table search routine generalized from Knuth (6.4) Algorithm D. 
It returns a pointer into a hash table indicating the location at which an entry can 
be found. The comparison function used by hsearch is strcmp [see string(3C)]. 
item is a structure of type ENTRY (defined in the search. h header file) containing 
two pointers: item.key points to the comparison key, and itemJata points to any 
other data to be associated with that key. (Pointers to types other than void 
should be cast to pointer-to-void.) action is a member of an enumeration type 
ACTION (defined in search . h) indicating the disposition of the entry if it cannot 
be found in the table. ENTER indicates that the item should be inserted in the 
table at an appropriate point. Given a duplicate of an existing item, the new item 
is not entered and hsearch returns a pointer to the existing item. FIND indicates 
that no entry should be made. Unsuccessful resolution is indicated by the return 
of a null pointer. 

hcreate allocates sufficient space for the table, and must be called before 
hsearch is used, nel is an estimate of the maximum number of entries that the 
table will contain. This number may be adjusted upward by the algorithm in 
order to obtain certain mathematically favorable circumstances. 

hdestroy destroys the search table, and may be followed by another call to 
hcreate. 

EXAMPLE 

The following example will read in strings followed by two numbers and store 
them in a hash table, discarding duplicates. It will then read in strings and find 
the matching entry in the hash table and print it out. 



♦include <stdio.h> 
♦include <search.h> 
♦include <string.h> 
♦include <stdlib.h> 



struct info { /* this is the info stored in table */ 

int age^ room; /* ot±ier than the key */ 

}; 



♦define NUM Et^L 



5000 



/* ♦ of elements in search table */ 



main( ) 



/* space to store strings */ 
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char string_space[NUM_EMPL*20] ; 

/* space to store errployee info */ 

struct info inf o__space [NUMJMPL] ; 

/* next avail space in string_space */ 

char *strjptr « string__space/ 

/* next avail space in info_space */ 

struct info *info_ptr = info_space/ 

ENTRY item;- ♦found__item; 

/* name to look for in table */ 

char name__to_f ind [ 30 ] ; 

int i = 0/ 

/* create table */ 
(void) hcreate (NUM_ML) / 

%rtiile (scanf ("%s%d%d", strjptr, &infojptr-->age, 

&infojptr->room) != EOF i++ < NOM_EMPL) { 
/* put info in structure, and structure in item */ 
item, key = str__ptr; 
item, data * (void *)infojptr; 
str_ptr +« strlen(str_ptr) + 1; 
infojptr++; 

/* put item into table */ 
(void) hsearch (item, ENTER); 

} 

/* access table */ 

item, key = name_to_find; 

v^ile (scanf ("%s", item, key) != EC^") { 

if ( (found__item = hsearch (item, FIND)) != NULL) { 
/* if item is in the table */ 
(void) printf ("found %s, age = %d, room = %d\n", 
f ound_it em->key , 

((struct info *) found_item->data)->age, 
((struct info *) found_item->data)->room) ; 
} else { 

(void) printf ( "no such employee %s\n", 
name_to__find) 

> 

} 

return 0; 

> 
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SEE ALSO 

bsearchOQ, IsearchOC), malloc(3C), mallocOX), string(3C), tsearch(3C). 
DIAGNOSTICS 

hsearch returns a null pointer if either the action is FIND and the item 
could not be found or the action is ENTER and the table is full. 

hcreate returns zero if it cannot allocate sufficient space for the table. 

NOTES 

hsearch and hcreate use inalloc(3C) to allocate space. 
Only one hash search table may be active at any given time. 
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NAME 

insque, reinque - insert/ remove element from a queue 

SYNOPSIS 

include <search.h> 

void insque (struct qelem *elem, struct qelem ♦pred) ; 
void remque (struct qelem '•'elem) ; 
DESCRIPTION 

insque and reinque manipulate queues built from doubly linked lists. Each ele- 
ment in the queue must be in the following form: 

struct qelem { 

struct qelem *q_forw; 

struct qelem *q_back; 
char qjdata [ ] ; 

}; 

insque inserts elem in a queue immediately after pred. remque removes an entry 
elem from a queue. 



10/89 



Page 1 



isnan(3C) 



isnan (3C) 



NAME 

isnan, isnand, isnanf, finite, fpclass, unordered - determine type of 
floating-point number 

SYNOPSIS 

♦include <ieeefp.h> 

int isnand (double dsrc) ; 
int isnanf (float f src) ; 
int finite (double dsrc) ; 
fpclass_t fpclass (double dsrc) ; 
int unordered (double dsrcl, double dsrc2) ; 
tinclude <math.h> 
int isnan (double dsrc); 
DESCRIPTION 

isnan, isnand, and isnanf return true (1) if the argument dsrc or fsrc is a NaN; 
otherwise they return false (0). The functionary of isnan is identical to that of 
isnand. 

isnanf is implemented as a macro included in the ieeefp.h header file. 

fpclass returns the class the dsrc belongs to. The 10 possible classes are as fol- 
lows: 



FP SNAN 


signaling NaN 


FP QNAN 


quiet NaN 


FPJJINF 


negative infinity 


FP PINF 


positive infinity 


FP NDENOBM 


negative denormalized non-zero 


FP PDENORM 


positive denormalized non-zero 


FP NZERO 


negative zero 


FP PZERO 


positive zero 


FP NNORM 


negative normalized non-zero 


FP PNORM 


positive normalized non-zero 



finite returns true (1) if the argument dsrc is neither infinity nor NaN; otherwise 
it returns false (0). 

unordered returns true (1) if one of its two argimients is unordered with respect 
to the other argument. This is equivalent to reporting whether either argimient is 
NaN. If neither of the arguments is NaN, false (0) is returned. 

None of these routines generate any exception, even for signaling NaNs. 

SEE ALSO 

fpgetroundOQ, introOM). 
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NAME 

IBtol, ItolS - convert between 3-byte integers and long integers 

SYNOPSIS 

♦include <stdlib.h> 

void IStol (long *lp, const char *cp, int n) ; 
void ItolS (char *cp^ const long *lp^ int n) ; 
DESCRIPTION 

IStol converts a list of n three-byte integers packed into a character string 
pointed to by cp into a list of long integers pointed to by Ip. 

ItolS performs the reverse conversion from long integers (Ip) to three-byte 
integers (cp). 

These fimctions are useful for file-system maintenance where the block numbers 
are three bytes long. 

SEE ALSO 

fs(4). 

NOTES 

Because of possible differences in byte ordering, the numerical values of the long 
integers are machine-dependent. 
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NAME 

localeconv - get numeric formatting information 

SYNOPSIS 

♦include <locale.h> 

struct Iconv * localeconv (void); 
DESCRIPTION 

localeconv sets the components of an object with type struct Iconv (defined 
in locale. h) with the values appropriate for the formatting of numeric quantities 
(monetary and otherwise) according to the rules of the current locale [see 
setlocaleOC)]. The definition of struct Iconv is given below (the values for 
the fields in the C locale are given in comments): 



char 


* deciinal_point ; 


/♦ 


"." */ 




char 


♦ thousands_sep ; 


/♦ 


"" (zero 


lei 


char 


♦grouping; 


/♦ 


♦/ 




char 


♦ intjcur r jsynibol ; 


/♦ 


♦/ 




char 


*currency__synibol ; 


/* 


„„ 




char 


♦mon_deciml_point; 


/♦ 






char 


♦xnon_thousands__sep ; 


/* 


nn 




char 


♦mon^grouping; 


/* 


nil 




char 


*positive_sign ; 


/♦ 


.III 




char 


*negative_sign ; 


/♦ 


.III */ 




char 


int_f racjdigit s ; 


/♦ 


CHAR MAX 


*/ 


char 


frac__digits; 


/* 


CHAR MAX 


*/ 


char 


p__cs_precedes ; 


/* 


CHAR MAX 


*/ 


char 


p_sep jDy_space ; 


/♦ 


CHAR MAX 


*/ 


char 


n_cs jprecedes ; 


/* 


CHAR MAX 


*/ 


char 


n__sep jDy_space ; 


/♦ 


CHAR MAX 


*/ 


char 


p_sign_posn; 


/* 


CHAR MAX 


*/ 


char 


n_sign_posn; 


/♦ 


C»AR MAX 


*/ 



The members of the structure with type char * are strings, any of which (except 
deciinal_point) can point to to indicate that the value is not available in the 
current locale or is of zero length. The members with type char are nonnegative 
numbers, any of which can be CHAR_MAX (defined in the limits. h header file) to 
indicate that the value is not available in the current locale. The members are the 
following: 

char *decimal_point 

The decimal-point character used to format non-monetary quantities. 

char *thousands__sep 

The character used to separate groups of digits to the left of the decimal- 
point character in formatted non-monetary quantities. 

char ^.grouping 

A string in which each element is taken as an integer that indicates the 
number of digits that comprise the current group in a formatted non- 
monetary quantity. The elements of grouping are interpreted according 
to the following: 
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CHAR-MAX No further grouping is to be performed. 

0 The previous element is to be repeatedly used for the 

remainder of the digits. 

other The value is the number of digits that comprise the current 

group. The next element is examined to determine the size 
of the next group of digits to the left of the current group. 

char *int_curr_synibol 

The international currency symbol applicable to the current locale, left- 
justified within a four-character space-padded field. The character 
sequences should match with those specified in: ISO 4217 Codes for the 
Representation of Currency and Funds. 

char *currency_syirbol 

The local currency symbol applicable to the current locale. 

char *roon_decimal_point 

The decimal point used to format monetary quantities. 

char *mon_thousandsjsep 

The separator for groups of digits to the left of the decimal point in for- 
matted monetary quantities. 

char *inon_groi:5)ing 

A string in which each element is taken as an integer that indicates the 
ntimber of digits that comprise the current group in a formatted mone- 
tary quantity. The elements of mon_grouping are interpreted according 
to the rules described under grouping. 

char *positive__sign 

The string used to indicate a nonnegative-valued formatted monetary 
quantity. 

char *negative_sign 

The string used to indicate a negative-valued formatted monetary quan- 
tity. 

char int__f racjdigits 

The number of fractional digits (those to the right of the decimal point) to 
be displayed in an internationally formatted monetary quantity. 

char f rac_digits 

The number of fractional digits (those to the right of the decimal point) to 
be displayed in a formatted monetary quantity. 

char p_csjprecedes 

Set to 1 or 0 if the currency__syntool respectively precedes or succeeds 
the value for a nonnegative formatted monetary quantity. 

char p_sep__byjspace 

Set to 1 or 0 if the currency_synbol respectively is or is not separated 
by a space from the value for a nonnegative formatted monetary quantity. 
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char n_jcs_precedes 

Set to 1 or 0 if the currency_svirbol respectively precedes or succeeds 
the value for a negative formatted monetary quantity. 

char n_sep_by_space 

Set to 1 or 0 if the currency_synibol respectively is or is not separated 
by a space from the value for a negative formatted monetary quantity. 

char p_sign_posn 

Set to a value indicating the positioning of the positive_sign for a non- 
negative formatted monetary quantity. The value of p_sign__posn is 
interpreted according to the following: 

0 Parentheses surroimd the quantity and currency_synix)l. 

1 The sign string precedes the quantity and currency_syitibol. 

2 The sign string succeeds the quantity and currency_synibol. 

3 The sign string immediately precedes the currency_syn)bol. 

4 The sign string immediately succeeds the currency_syinbol. 

char n__sign_j>osn 

Set to a value indicating the positioning of the negative_sign for a 
negative formatted monetary quantity. The value of n__signjposn is 
interpreted according to the rules described under p_signjf>osn. 

EXAMPLES 

The following table illustrates the rules used by four countries to format mone- 
tary quantities. 

Country Positive format Negative format International format 

Italy L.1.234 -L.1.234 ITL.1.234 

Netherlands F 1 .234^6 F -1 .234,56 NLG 1 .234,56 

Norway krl .234,56 krl .234,56- NOK 1.234,56 

Switzerland SFrs.1,234.56 SFrs.l,234.56C CHF 1,234.56 

For these four countries, the respective values for the monetary members of the 
structure returned by localeconv are as follows: 

Italy Netherlands Norway Switzerland 



int_curr_syntool 


"ITL." 


"NLG " 


"NOK " 


"CHF " 


currency__syirbol 


"L . " 


lip 11 


"kr" 


"SFrs." 


inDn__decixnalj>oint 


It II 


II II 

t 


11 II 

r 


II II 


xnon_thousands_sep 


II II 


II II 


II 11 


II II 


xnon^grouping 


"\3" 


"\3" 


"\3" 


"\3" 


positive_sign 


II It 


II II 


II II 


II II 


negative_sign 


ii_ii 


ii__ii 


ii__ii 


"C" 


int_frac_digits 


0 


2 


2 


2 


fracjdigits 


0 


2 


2 


2 


p__cs_precedes 


1 


1 


1 


1 


p__sep_by_space 


0 


1 


0 


0 


n_cs_j>recedes 


1 


1 


1 


1 
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n_sep_jDy_space 

p_sign_posn 

n__sign_posn 



0 
1 
1 



1 
1 
4 



0 
1 
2 



0 
1 
2 



FILES 



/usr/lib/locale/Zocak/LCMONETARY 
/usr/lib/locale/Zoc<ite/IiC NUMERIC 



LC_MONETARY database for locale 
LC NUMERIC database for locale 



SEE ALSO 

chrtbl(lM), nontJDl(lM), setlocale(3C). 
DIAGNOSTICS 

localeconv returns a pointer to the filled-in object. The structure pointed to by 
the return value may be overwritten by a subsequent call to localeconv. 
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NAME 

lockf - record locking on files 

SYNOPSIS 

♦include <unistd.h> 

int lockf (int fildes, int function, long size); 
DESCRIPTION 

lockf allows sections of a file to be locked; advisory or mandatory write locks 
depending on the mode bits of the file [see chmod(2)]. Locking calls from other 
processes that attempt to lock the locked file section will either return an error 
value or be put to sleep until the resource becomes unlocked. All the locks for a 
process are removed when the process terminates. [See f cntl(2) for more infor- 
mation about record locking.] 

fildes is an open file descriptor. The file descriptor must have 0_WRC»ILY or 
0_RDWR permission in order to establish locks with this function call. 

function is a control value that specifies the action to be taken. The permissible 
values for function are defined in unistd.h as follows: 

♦define FJCJLOCK 0 /* unlock previously locked section */ 
tdefine F__LOCK 1 /* lock section for exclusive use */ 
♦define FETLOCK 2 /* test & lock section for exclusive use */ 
♦define FJTEST 3 /* test section for other locks */ 

All other values of function are reserved for future extensions and will result in an 
error return if not implemented. 

F__TEST is used to detect if a lock by another process is present on the specified 
section. F_LOCK and FJTLOCK both lock a section of a file if the section is avail- 
able. FJCJLOCK removes locks from a section of the file. 

size is the number of contiguous bytes to be locked or unlocked. The resource to 
be locked or imlocked starts at the current offset in the file and extends forward 
for a positive size and backward for a negative size (the preceding bytes up to 
but not including the current offset). If size is zero, the section from the current 
offset through the largest file offset is locked (i.e., from the current offset through 
the present or any future end-of-file). An area need not be allocated to the file in 
order to be locked as such locks may exist past the end-of-file. 

The sections locked with F__LOCK or F_TLOCK may, in whole or in part, contain or 
be contained by a previously locked section for the same process. Locked sec- 
tions will be imlocked starting at the the point of the offset through size bytes or 
to the end of file if size is (of f__t) 0. When this situation occurs, or if this situa- 
tion occurs in adjacent sections, the sections are combined into a single section. If 
the request requires that a new element be added to the table of active locks and 
this table is already full, an error is returned, and the new section is not locked. 

F_I/X3C and FjnOCK requests differ only by the action taken if the resource is not 
available. F_LOCK will cause the calling process to sleep until the resource is 
available. F_TLOCK will cause the function to return a -1 and set errno to 
EACCES if the section is already locked by another process. 
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F_ULCX:k requests may, in whole or in part, release one or more locked sections 
controlled by the process. When sections are not fully released, the remaining 
sections are still locked by the process. Releasing the center section of a locked 
section requires an additional element in the table of active locks. If this table is 
full, an errno is set to ENOLK and the requested section is not released. 

A potential for deadlock occurs if a process controlling a locked resource is put to 
sleep by requesting another process's locked resource. Thus calls to lockf or 
fcntl scan for a deadlock prior to sleeping on a locked resource. An error 
return is made if sleeping on the locked resource would cause a deadlock. 

Sleeping on a resource is interrupted with any signal. The alarm system call may 
be used to provide a timeout facility in applications that require this facility. 

lockf will fail if one or more of the following are true: 

EBADF fildes is not a valid open descriptor. 

EAGAIN and is FJTLOCK or FJTEST and the section is already locked by 
another process. 

EDEADLK and is F__LOCK and a deadlock would occur. 

ENOLK and is F_LOCK, F_TLOCK, or FJCJLOCK and the number of entries in 

the lock table would exceed the number allocated on the system. 

ECOftW fildes is on a remote machine and the link to that machine is no 
longer active. 

SEE ALSO 

intro(2), alann(2), chmod(2), close(2), creat(2), fcntl(2), open(2), read(2), 
write(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and ermo is set to indicate the error. 

NOTES 

Unexpected results may occur in processes that do buffering in the user address 
space. The process may later read /write data that is/ was locked. The standard 
I/O package is the most common source of unexpected buffering. 

Because in the future the variable errno will be set to EAGAIN rather than EACCES 
when a section of a file is already locked by another process, portable application 
programs should expect and test for either value. 
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NAME 

Isearch, If ind - linear search and update 

SYNOPSIS 

♦include <search.h> 

void ♦Isearch (const void *key, void * base, size_t *nelp, 

size_t width, int (*cornpeu:) (const void *, const void ♦)); 

void *lfind (const void *key, const void *base, size_t *nelp, 
size_t width, int (*coinpar) (const void *, const void *)); 

DESCRIPTION 

Isearch is a linear search routine generalized from Knuth (6.1) Algorithm S. It 
returns a pointer into a table indicating where a datum may be found. If the 
datum does not occur, it is added at the end of the table, key points to the datum 
to be sought in the table, base points to the first element in the table, nelp points 
to an integer containing the current number of elements in the table. The integer 
is incremented if the datum is added to the table, width is the size of an element 
in bytes, compar is a pointer to the comparison function that the user must supply 
(strcnp, for example). It is called with two arguments that point to the elements 
being compared. The function must return zero if the elements are equal and 
non-zero otherwise. 

If ind is the same as Isearch except that if the datum is not found, it is not 
added to the table. Instead, a null pointer is returned. 

NOTES 

The pointers to the key and the element at the base of the table may be pointers 
to any t)^. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

The value returned should be cast into type pointer-to-element. 

EXAMPLE 

This program will read in less than TABSIZE strings of length less than ELSIZE 
and store them in a table, eliminating duplicates, and then will print each entry. 

♦include <search.h> 
♦include <string.h> 
♦include <stdlib.h> 
♦include <stdio.h> 

♦define TABSIZE 50 
♦define ELSIZE 120 

mainO 
{ 

char line [ELSIZE] ; /* buffer to hold ir^ut string */ 
char tab [TABSIZE] [ELSIZE]; /* table of strings */ 
size_t nel = 0; /* nurnber of entries in tab */ 

int i; 
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ii^ile (fgetsdine, ELSIZE, stdin) NULL && 
nel < TABSIZE) 

(void) Isearchdine, tab, &nel, ELSIZE, xnycnp) ; 
for( i » 0; i < nel; i++ ) 

(void) fputs (tab [ i ] , stdout ) ; 
return 0; 

} 

SEE ALSO 

bsearchOO, hsearch(3C), string(3C), tsearchOC). 

NOTES 

If the searched-for datum is found, both Isearch and Ifind return a pointer 
to it. Otherwise, Ifind returns NULL and Isearch returns a pointer to the 
newly added element. 

Undefined results can occur if there is not enough room in the table to add 
a new item. 
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NAME 

malloc, free, reallcx:, calloc - memory allocator 

SYNOPSIS 

♦include <stdlib.h> 

void *inalloc (sizejt size) ; 
void free (void ♦ptr) ; 
void *realloc (void ♦ptr, sizejt size) ; 
void ♦calloc (size_t nelem, size_t elsize) ; 
DESCRIPTION 

malloc and free provide a simple general-purpose memory allocation package, 
malloc returns a pointer to a block of at least size bytes suitably aligned for any 
use. 

The argument to free is a pointer to a block previously allocated by malloc, 
calloc or realloc. After free is performed this space is made available for 
further allocation. If ptr is a NULL pointer, no action occurs. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

realloc changes the size of the block pointed to by ptr to size bytes and returns 
a pointer to the (possibly moved) block. The contents will be unchanged up to 
the lesser of the new and old sizes. If ptr is WILL, realloc behaves like xnalloc 
for the specified size. If size is zero and ptr is not a null pointer, the object 
pointed to is freed. 

calloc allocates space for an array of nelem elements of size elsize. The space is 
initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

malloc, realloc, and calloc will fail if there is not enough available memory. 

SEE ALSO 

mallocOX). 

DIAGNOSTICS 

If there is no available memory, malloc, realloc, and calloc return a null 
pointer. When realloc returns NULL, the block pointed to by ptr is left intact. If 
size, nelem or elsize is 0, a unique pointer to the arena is returned. 
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NAME 

irbchar: xrbtowc, irblen, wctoirb - multibyte character handling 

SYNOPSIS 

♦include <stdlib.h> 

int ntotowc (wchar_t *pwc, const char *s, size_t n) ; 
int ntolen (const char *3, size_t n); 
int wctomb (char *s, wchar_t wchar); 
DESCRIPTION 

Multibyte characters are used to represent characters in an extended character set. 
This is needed for locales where 8 bits are not enough to represent all the charac- 
ters in the character set. 

The multibyte character handling functions provide the means of translating mul- 
tibyte characters into wide characters and back again. Wide characters have type 
wchar_t (defined in stdlib.h), which is an integral type whose range of values 
can represent distinct codes for all members of the largest extended character set 
specified among the supported locales. 

A maximum of 3 extended character sets are supported for each locale. The 
number of bytes in an extended character set is defined by the LC_CTYPE category 
of the locale [see setlocale(3C)]. However, the maximimi number of bytes in 
any multibyte character will never be greater than M3_LEN__MAX (see stdliJb.h). 
The maximum number of bytes in a character in an extended character set in the 
current locale is given by the macro MBjCUR_MAX (see stdlib.h). 

itibtowc determines the number of bytes that comprise the multibyte character 
pointed to by s. Also, if pwc is not a null pointer, irbtowc converts the multibyte 
character to a wide character and places the result in the object pointed to by pwc. 
(The value of the wide character corresponding to the null character is zero.) At 
most n characters will be examined, starting at the character pointed to by s. 

If s is a null pointer, irbtowc simply returns 0. If s is not a null pointer, then, if s 
points to the null character, irbtowc returns 0; if the next n or fewer bytes form a 
valid multibyte character, irbtowc returns the number of bytes that comprise the 
converted multibyte character; otherwise, s does not point to a valid multibyte 
character and irbtowc returns -1. 

irblen determines the number of bytes comprising the multibyte character 
pointed to by s. It is equivalent to 

irbtowc ((wchar__t *)0, s, n) ; 

wctonb determines the number of bytes needed to represent the multibyte charac- 
ter corresponding to the code whose value is wchar, and, if s is not a null pointer, 
stores the multibyte character representation in the array pointed to by s. At 
most MB CUR MAX characters are stored. 
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If s is a null pointer, wctonib simply returns 0. If s is not a null pointer, wctonib 
returns - 1 if the value of wchar does not correspond to a valid multibyte charac- 
ter; otherwise it returns the number of bytes that comprise the multibyte charac- 
ter corresponding to the value of wchar, 

SEE ALSO 

chrtbl(lM), nibstring(3C), setlocale(3C), environ(5). 
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NAME 

mbstring: irbstowcs, wcstoxrbs - multibyte string functions 

SYNOPSIS 

♦include <stdlib.h> 

sizejt mbstowcs (wcharjt *pwcs, const char *3, size_t n) / 
sizejt wcstornbs (char *s, const wchar_t *pwc8, size_t n) ; 
DESCRIPTION 

icbstowcs converts a sequence of multibyte characters from the array pointed to 
by s into a sequence of corresponding wide character codes and stores these 
codes into the array pointed to by pwcs, stopping after n codes are stored or a 
code with value zero (a converted null character) is stored. If an invalid multi- 
byte character is encountered, irbstowcs returns (size__t)-l. Otherwise, 
irbstowcs returns the number of array elements modified, not including the ter- 
minating zero code, if any. 

wcstoirbs converts a sequence of wide character codes from the array pointed to 
by pwcs into a sequence of multibyte characters and stores these multibyte charac- 
ters into the array pointed to by s, stopping if a multibyte character would exceed 
the limit of n total bytes or if a null character is stored. If a wide character code 
is encountered that does not correspond to a valid multibyte character, wcstontos 
returns (size__t)-l. Otherwise, wcstombs returns the number of bytes modified, 
not including a terminating null character, if any. 

SEE ALSO 

chrtbl(lM), irbchar(3C), setlocale(3C), environ(5). 
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NAME 

xnemozy: memccpy, memchr, memcmp, memqpy, memnove, memset - memory opera- 
tions 

SYNOPSIS 

tinclude <strin9.h> 

void *ineincqpy (void *sl, const void *s2, int sizejt n) ; 
void *memchr (const void ♦s, int c, size_t n) ; 
int memcnp (const void ♦si, const void *s2, size_t n); 
void *ineincpy (void *sl, const void *s2, size_t n) ; 
void *X!ieninDve (void *sl, const void *s2, size_t n) ; 
void *nieinset (void *a, int c, sizejt n) ; 
DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays of 
bytes bounded by a count, not terminated by a null character). They do not 
check for the overflow of any receiving memory area. 

memccpy copies bytes from memory area s2 into si, stopping after the first 
occurrence of c (converted to an unsigned char) has been copied, or after n 
bytes have been copied, whichever comes first. It returns a pointer to the byte 
after the copy of c in si, or a null pointer if c was not found in the first n bytes 
of s2. 

memchr returns a pointer to the first occurrence of c (converted to an unsigned 
char) in the first n bytes (each interpreted as an unsigned char) of memory area 
s, or a null pointer if c does not occur. 

memcaip compares its arguments, looking at the first n bytes (each interpreted as 
an unsigned char), and returns an integer less than, equal to, or greater than 0, 
according as si is lexicographically less than, equal to, or greater than s2 when 
taken to be unsigned characters. 

memc^ copies n bytes from memory area s2 to si . It returns si . 

memmove copies n bytes from memory areas s2 to si. Copying between objects 
that overlap will take place correctly. It returns si. 

memset sets the first n bytes in memory area s to the value of c (converted to an 
unsigned char). It returns s. 

SEE ALSO 

string(3C). 
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NAME 

rokf if o - create a new FIFO 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/stat.h> 

int xiikfifo (const char *path, xnodejt mode) ; 
DESCRIPTION 

The mkf ifo routine creates a new FIFO special file named by the pathname 
pointed to by path. The mode of the new FIFO is initialized from mode. The file 
permission bits of the mode argument are modified by the process's file creation 
mask [see uinask(2)]. 

The FIFO's owner id is set to the process's effective user id. The FIFO's group id 
is set to the process's effective group id, or if the S_ISGID bit is set in the parent 
directory then the group id of the FIFO is inherited from the parent. 

mlcfifo calls the system call mknod to make the file. 

SEE ALSO 

chinod(2), exec(2), inknod(2), uinask(2), f s(4), stat(5). 
mkdird) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 

NOTES 

Bits other than the file permission bits in mode are ignored. 
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NAME 

mktenp - make a unique file name 

SYNOPSIS 

♦include <stdlib.h> 

char *inktenp (char *texrplate) ; 

DESCRIPTION 

mktenp replaces the contents of the string pointed to by template with a unique 
file name, and returns template. The string in template should look like a file 
name with six trailing Xs; inkteirp will replace the Xs with a character string that 
can be used to create a unique file name. 

SEE ALSO 

t:xipf ile(3S), t:irpnam(3S). 

DIAGNOSTIC 

mktenp will assign to template the empty string if it cannot create a unique name. 

NOTES 

mktenp can create only 26 unique file names per process for each unique template. 
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b 


tm { 


int 


tm_sec; 


int 


tmjnin; 


int 


tm_hour; 


int 


tmjnday; 


int 


tmjnon; 


int 


tin_year; 


int 


tmjwday; 


int 


tm_yclay; 


int 


tm isdst; 



NAME 

mktime - converts a tm structure to a calendar time 

SYNOPSIS 

♦include <time.h> 

timejt mktime (struct tm ♦timeptr) ; 
DESCRIPTION 

mktime converts the time represented by the tm structure pointed to by timeptr 
into a calendar time (the number of seconds since 00:00:00 UTQ January 1, 1970). 

The tm structure has the following format. 

/* seconds after the mdLnute [0, 61] */ 
/* minutes after the hour [0^ 59] */ 
/* hour since midnight [0, 23] */ 
/* day of the month [1, 31] */ 
/* months since January [0, 11] */ 
/* years since 1900 */ 
/* days since Sunday [0, 6] */ 
/* days since January 1 [0, 365] */ 
/* flag for daylight savings time */ 

}; 

In addition to computing the calendar time, mktime normalizes the supplied tm 
structure. The original values of the tmjwday and tm__yday components of the 
structure are ignored, and the original values of the other components are not 
restricted to the ranges indicated in the definition of the structure. On successful 
completion, the values of the tmjwday and t:m_yday components are set appropri- 
ately, and the other components are set to represent the specified calendar time, 
but with their values forced to be within the appropriate ranges. The final value 
of t:m__mday is not set until t:m_jiK>n and t:m_year are determined. 

The original values of the components may be either greater than or less than the 
specified range. For example, a tm_hour of -1 means 1 hour before midnight, 
tun_mday of 0 means the day preceding the current month, and tmjnon of -2 
means 2 months before January of tm__year. 

If tm__isdst is positive, the original values are assumed to be in the alternate 
timezone. If it turns out that the alternate timezone is not valid for the computed 
calendar time, then the components are adjusted to the main timezone. Likewise, 
if tm_isdst is zero, the original values are assumed to be in the main timezone 
and are converted to the alternate timezone if the main timezone is not valid. If 
tm__isdst is negative, the correct timezone is determined and the components are 
not adjusted. 

Local timezone information is used as if mktime had called tzset. 

mktime returns the specified calendar time. If the calendar time cannot be 
represented, the function returns the value (time_t)-l. 
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EXAMPLE 

What day of the week is July A, 2001? 

♦include <stdio.h> 
tinclude <tiine.h> 

static char * const wday [ ] = { 

"Sunday", "Monday", "Tuesday", "Wednesday", 
"Thursday", "Friday", "Saturday", "-\inknown-" 

}/ 

struct tm tiine__str; 
/*...*/ 

tiine_str.tm_year= 2001 - 1900; 
tiine_str . tmjnon * 7 - 1; 
tiine_str.tmjnday= 4; 
tixne_str.tm_hour= 0; 
tiine_str . tmjnin = 0; 
time_str . tm_sec = 1; 

time^str . tm_isdst = -1; 
if {xnlctixne(&tiiiie_str)= -1) 

time^str . tmjwday=7 ; 
printf ("%s\n" , wday [ time_str . tunjwday] ) ; 

SEE ALSO 

ctimeOC), getenv(3C), tiinezone(4). 

NOTES 

tin_year of the tm structure must be for year 1970 or later. Calendar times before 
00:00:00 UTQ January 1, 1970 or after 03:14:07 UTC, January 19, 2038 cannot be 
represented. 



Page 2 



10/89 



monitor (3C) 



monitor (3C) 



NAME 

monitor - prepare execution profile 

SYNOPSiS 

♦include <mon.h> 

void monitor (int (*lowpc) ( ) , int (*highpc) ( ) , WORD *buffer, 
size_t bufsize, sizejt nfunc) ; 

DESCRIPTION 

monitor is an interface to prof il, and is called automatically with default 
parameters by any program created by cc -p. Except to establish further control 
over profiling activity, it is not necessary to explicitly call monitor. 

When used, monitor is called at least at the beginning and the end of a program. 
The first call to monitor initiates the recording of two different kinds of 
execution-profile information: execution-time distribution and function call count. 
Execution-time distribution data is generated by prof il and the function call 
counts are generated by code supplied to the object file (or files) by cc -p. Both 
types of information are coUectai as a program executes. The last call to moni- 
tor writes this collected data to the output file mon . out. 

lozvpc and higkpc are the beginning and ending addresses of the region to be 
profiled. 

buffer is the address of a user-supplied array of WORD (WORD is defined in the 
header file mon.h). buffer is used by monitor to store the histogram generated by 
prof il and the call coimts. 

bufsize identifies the number of array elements in buffer. 

nfunc is the number of call count cells that have been reserved in buffer. Addi- 
tional call count cells will be allocated automatically as they are needed. 

bufsize should be computed using the following formula: 

sizejof__buffer = 

sizeof (struct hdr) + 

nfunc * sizeof (struct cnt) + 

( (hicflipc-lowpc) /BARSIZE) * sizeof (WORD) + 

sizeof (WORD) - 1 ; 

bufsize = (size_pfjbuffer / sizeof (WORD) ) ; 

where: 

lowpc, highpc, nfunc are the same as the arguments to monitor; 

BARSIZE is the number of program bytes that correspond to each histo- 
gram bar, or cell, of the prof il buffer; 

the hdr and cnt structures and the t5^e WORD are defined in the header 
file mon.h. 
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The default call to monitor is shown below: 

monitor (&eprol, ftetext^ wbuf, i^ufsz, 600) ; 

where: 

eprol is the beginning of the user's program when linked with cc -p [see 
end(3C)]; 

etext is the end of the user's program [see end(3C)]; 
wbuf is an array of WORD with wbufsz elements; 

zvbufsz is computed using the bufsize formula shown above with BARSIZE 
of 8; 

600 is the number of call count cells that have been reserved in buffer. 

These parameter settings establish the computation of an execution-time distribu- 
tion histogram that uses prof il for the entire program, initially reserves room 
for 600 call count cells in buffer, and provides for enough histogram cells to gen- 
erate significant distribution-measurement results. [For more information on the 
effects of bufsize on execution-distribution measurements, see prof il(2).] 

To stop execution monitoring and write the results to a file, use the following: 

monitor((int (*)())0, (int (*)())0, (WORD *)0, 0, 0) ; 

Use prof to examine the results. 

FILES 

mon . out 

SEE ALSO 

cc(l), prof (1), prof il(2), end(3C). 

NOTE 

Additional calls to monitor after main has been called and before exit has been 
called will add to the function-call coimt capacity, but such calls will also replace 
and restart the prof il histogram computation. 

The name of the file written by monitor is controlled by the environment vari- 
able PROFDIR. If PROFDIR does not exist, the file mon. out is created in the 
current directory. If PROFDIR exists but has no value, monitor does no profiling 
and creates no output file. If PROFDIR is dirname, and monitor is called automati- 
cally by compilation with cc -p, the file created is dirname /pid.progname where 
progname is the name of the program. 
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NAME 

of f setof - offset of structure member 

SYNOPSIS 

♦include <stddef .h> 

sizejt off setof (type^ xnentoer-designator) ; 
DESCRIPTION 

of f setof is a macro defined in stddef . h which expands to an integral constant 
expression that has type size_t, the value of which is the offset in bytes, to the 
structure member (designated by member-designator), from the beginning of its 
structure (designated by type). 
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NAME 

perror - print system error messages 

SYNOPSIS 

♦include <stdio.h> 

void perror (const char *s) ; 

DESCRIPTION 

perror produces a message on the standard error output (file descriptor 2), 
describing the last error encountered during a call to a system or library function. 
The argument string s is printed first, then a colon and a blank, then the message 
and a newline. (However, if s is a null pointer or points to a null string, the 
colon is not printed.) To be of most use, the argument string should include the 
name of the program that incurred the error. The error ntmiber is taken from the 
external variable errno, which is set when errors occur but not cleared when 
non-erroneous calls are made. 

SEE ALSO 

intrc>(2), fmtxnsg(3C), strerror(3C). 
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NAME 

pqpen, pclose - initiate pipe to/from a process 

SYNOPSIS 

♦include <stdio.h> 

FILE *popen (const char *coitinand, const char *type) ; 
int pclose (FILE * stream) ; 
DESCRIPTION 

popen creates a pipe between the calling program and the command to be exe- 
cuted. The arguments to popen are pointers to null-terminated strings, command 
consists of a shell command line, type is an I/O mode, either r for reading or w 
for writing. The value returned is a stream pointer such that one can write to the 
standard input of the command, if the I/O mode is w, by writing to the file stream 
[see intro(3)]; and one can read from the standard output of the command, if the 
I/O mode is r, by reading from the file stream. 

A stream opened by popen should be closed by pclose, which waits for the asso- 
ciated process to terminate and returns the exit status of the command. 

Because open files are shared, a type r command may be used as an input filter 
and a type w as an output filter. 

EXAMPLE 

Here is an example of a typical call: 

♦include <stdio.h> 
# include <stdlib.h> 

mainO 
{ 

char *cml = "/usr/bin/ls *.c"; 
char buf [BUFSIZ3; 
FILE *ptr; 

if ((ptr = popen (cmd, "r")) != NULL) 

while (fgets(buf, BUFSIZ, ptr) != NULL) 
(void) printf("%s", buf ) ; 

return 0; 

} 

This program will print on the standard output [see stdio(3S)] all the file names 
in the current directory that have a . c suffix. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), stdio(3S), systemOS). 
DIAGNOSTICS 

popen returns a null pointer if files or processes cannot be created, 
pclose returns -1 if stream is not associated with a popened command. 
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NOTES 

If the original and popened processes concurrently read or write a common file, 
neither should use buffered I/O. Problems with an output filter may be 
forestalled by careful buffer flushing, e.g., with f flush [see fclose(3S)]. 

A security hole exists through the IFS and PATH environment variables. Full 
pathnames should be used (or PATH reset) and IFS should be set to space and tab 
(" \t"). 
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NAME 

printf, fprintf, sprintf - print formatted output 

SYNOPSIS 

♦include <stdio.h> 

int print f (const char * format, .../* args */) ; 
int fjprintf (FILE *strm, const char * format, . . ./* args */); 
int sprintf (char *s, const char *fonnat, .../* args */) / 
DESCRIPTION 

printf places output on the standard output stream stdout. 
fprintf places output on strm. 

sprintf places output, followed by the null character (\0), in consecutive bytes 
starting at s. It is the user's responsibility to ensure that enough storage is avail- 
able. Each fimction returns the number of characters transmitted (not including 
the \0 in the case of sprintf) or a negative value if an output error was encoun- 
tered. 

Each of these functions converts, formats, and prints its args under control of the 
format The format is a character string that contains three types of objects defined 
below: 

1. plain characters that are simply copied to the output stream; 

2. escape sequences that represent non-graphic characters; 

3. conversion specifications. 

The following escape sequences produce the associated action on display devices 
capable of the action: 

\a Alert. Ring the bell. 

\b Backspace. Move the printing position to one character before the current 
position, unless the current position is the start of a line. 

\f Form feed. Move the printing position to the initial printing position of 
the next logical page. 

\n Newline. Move the printing position to the start of the next line. 

\r Carriage return. Move the printing position to the start of the current 
line. 

\t Horizontal tab. Move the printing position to the next implementation- 
defined horizontal tab position on the current line. 

\v Vertical tab. Move the printing position to the start of the next 
implementation-defined vertical tab position. 

All forms of the printf functions allow for the insertion of a language-dependent 
decimal-point character. The decimal-point character is defined by the program's 
locale (category LC_NUMERIC). In the C locale, or in a locale where the decimal- 
point character is not defined, the decimal-point character defaults to a period ( . ). 
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Each conversion specification is introduced by the character %. After the charac- 
ter %, the following appear in sequence: 

An optional field, consisting of a decimal digit string followed by a $, 
specifying the next args to be converted. If this field is not provided, the 
args following the last args converted will be used. 

Zero or more flags, which modify the meaning of the conversion 
specification. 

An optional string of decimal digits to specify a minimum field width. If 
the converted value has fewer characters than the field width, it will be 
padded on the left (or right, if the left-adjustment flag (-), described 
below, has been given) to the field width. 

An optional precision that gives the minimum number of digits to appear 
for the d, i, o, u, x, or X conversions (the field is padded with leading 
zeros), the number of digits to appear after the decimal-point character for 
the e, E, and f conversions, the maximum number of significant digits for 
the g and G conversions, or the maximum number of characters to be 
printed from a string in s conversion. The precision takes the form of a 
period ( . ) followed by a decimal digit string; a null digit string is treated 
as zero. Padding specified by the precision overrides the padding 
specified by the field width. 

An optional h specifies that a following d, i, o, u, x, or X conversion 
specifier applies to a short int or unsigned short int argument (the 
argument will be promoted according to the integral promotions and its 
value converted to short int or unsigned short int before printing); 
an optional h specifies that a following n conversion specifier applies to a 
pointer to a short int argument. An optional 1 (ell) specifies that a fol- 
lowing d, i, o, u, X, or X conversion specifier applies to a long int or 
unsigned long int argimient; an optional 1 (ell) specifies that a follow- 
ing n conversion specifier applies to a pointer to long int argument. An 
optional L specifies that a following e, E, f, g, or G conversion specifier 
applies to a long double argimient. If an h, 1, or L appears before any 
other conversion specifier, the behavior is undefined. 

A conversion character (see below) that indicates the type of conversion to 
be applied. 

A field width or precision may be indicated by an asterisk (*) instead of a digit 
string. In this case, an integer args supplies the field width or precision. The args 
that is actually converted is not fetched until the conversion letter is seen, so the 
args specifying field width or precision must appear before the args (if any) to be 
converted. If the precision argument is negative, it will be changed to zero. A 
negative field width argument is taken as a - flag, followed by a positive field 
width. 

In format strings containing the *digits$ form of a conversion specification, a field 
width or precision may also be indicated by the sequence '^digits$, giving the 
position in the argument list of an integer args containing the field width or preci- 
sion. 
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When numbered argument specifications are used, specifying the Nth argument 
requires that all the leading arguments, from the first to the (N-l)th, be specified 
in the format string. 

The flag characters and their meanings are: 

The result of the conversion will be left-justified within the field. (It will 
be right-justified if this flag is not specified.) 

+ The result of a signed conversion will always begin with a sign (+ or -). 
(It will begin with a sign only when a negative value is converted if this 
flag is not specified.) 

space If the first character of a signed conversion is not a sign, a space will be 
placed before the result. This means that if the space and + flags both 
appear, the space flag will be ignored. 

# The value is to be converted to an alternate form. For c, d, i, s, and u 
conversions, the flag has no effect. For an o conversion, it increases the 
precision to force the first digit of the result to be a zero. For x (or X) 
conversion, a non-zero result will have Ox (or 030 prepended to it. For e, 
E, f, g, and G conversions, the result will always contain a decimal-point 
character, even if no digits follow the point (normally, a decimal point 
appears in the result of these conversions only if a digit follows it). For g 
and G conversions, trailing zeros will not be removed from the result as 
they normally are. 

0 For d, i, o, u, x, X, e, E, f , g, and G conversions, leading zeros (following 
any indication of sign or base) are used to pad to the field width; no space 
padding is performed. If the 0 and - flags both appear, the 0 flag will be 
ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 
0 flag will be ignored. For other conversions, the behavior is undefined. 

Each conversion character results in fetching zero or more orgs. The results are 
undefined if there are insufficient args for the format. If the format is exhausted 
while args remain, the excess args are ignored. 

The conversion characters and their meanings are: 

d,i,o,u,x,X The integer arg is converted to signed decimal (d or i), (imsigned 
octal (o), unsigned decimal (u), or unsigned hexadecimal notation 
(x and X). The x conversion uses the letters abcdef and the X 
conversion uses the letters ABCDEF. The precision specifies the 
minimum number of digits to appear. If the value being con- 
verted can be represented in fewer digits than the specified 
minimum, it will be expanded with leading zeros. The default 
precision is 1. The result of converting a zero value with a preci- 
sion of zero is no characters. 

f The double args is converted to decimal notation in the style 

[-]ddd.ddd, where the number of digits after the decimal-point 
character [see setlocale(3C)l is equal to the precision 
specification. If the precision is omitted from arg, six digits are 
output; if the precision is explicitly zero and the # flag is not 
specified, no decimal-point character appears. If a decimal-point 
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character appears, at least 1 digit appears before it. The value is 
rounded to the appropriate number of digits. 

e,E The double args is converted to the style [-\d .dddekdd, where 

there is one digit before the decimal-point character (which is 
non-zero if the argument is non-zero) and the number of digits 
after it is equal to the precision. When the precision is missing, 
six digits are produced; if the precision is zero and the # flag is 
not specified, no decimal-point character appears. The E conver- 
sion character will produce a number with E instead of e intro- 
ducing the exponent. The exponent always contains at least two 
digits. The value is rounded to the appropriate number of digits. 

g,G The double args is printed in style f or e (or in style E in the case 

of a G conversion character), with the precision specifying the 
number of significant digits. If the precision is zero, it is taken as 
one. The style used depends on the value converted: style e (or 
E) will be used only if the exponent resulting from the conver- 
sion is less than -4 or greater than or equal to the precision. 
Trailing zeros are removed from the fractional part of the result. 
A decimal-point character appears only if it is followed by a 
digit. 

c The int args is converted to an unsigned char, and the result- 

ing character is printed. 

s The args is taken to be a string (character pointer) and characters 

from the string are written up to (but not including) a terminat- 
ing null character; if the precision is specified, no more than that 
many characters are written. If the precision is not specified, it is 
taken to be infinite, so all characters up to the first null character 
are printed. A NULL value for args will yield undefined results. 

p The args should be a pointer to void. The value of the pointer is 

converted to an implementation-defined set of sequences of 
printable characters, which should be the same as the set of 
sequences that are matched by the %p conversion of the scanf 
function. 

n The argument should be a pointer to an integer into which is 

written the number of characters written to the output standard 
I/O stream so far by this call to print f, fprintf, or sprintf . 
No argument is converted. 

% Print a %; no argument is converted. 

If the character after the % or %digits$ sequence is not a valid conversion character, 
the results of the conversion are undefined. 

If a floating-point value is the internal representation for infinity, the output is 
[±]m/, where inf is either inf or INF, depending on the conversion character. 
Printing of the sign follows the rules described above. 
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If a floating-point value is the internal representation for "not-a-number/' the 
output is l±]nanOxm. Depending on the conversion character, nan is either nan or 
NAN. Additionally, Oxm represents the most significant part of the mantissa. 
Again depending on the conversion character, x will be x or X, and m will use the 
letters abcdef or ABCDEF. Printing of the sign follows the rules described above. 

In no case does a non-existent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is simply 
expanded to contain the conversion result. Characters generated by printf and 
fprintf are printed as if the putc routine had been called. 

EXAMPLE 

To print a date and time in the form Sunday, July 3, 10:02, where weekday 
and month are pointers to null-terminated strings: 

printf ("%s, %s %i, %d:%.2d", 

weekday, month, day, hour, min) ; 

To print 7t to 5 decimal places: 

printf ("pi = %.5f", 4 * atan(l.O)); 

SEE ALSO 

exit(2), lseek(2), write(2), abortOC), ecvt(3C), putc(3S), scanf(3S), 
setlocaleOC), stdio(3S). 

DIAGNOSTICS 

printf, fprintf, and sprintf return the number of characters transmitted, or 
return a negative value if an error was encountered. 
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NAME 

putc, putchar, Q>utc, putw - put character or word on a stream 

SYNOPSIS 

♦include <stdio.h> 

int putc (int FILE * stream) ; 
int putchar (int c) ; 
int Q)utc (int c, FILE ^stream) ; 
int putw (int w, FILE * stream) ; 
DESCRIPTION 

putc writes c (converted to an unsigned char) onto the output stream [see 
intro(3)] at the position where the file pointer (if defined) is pointing, and 
advances the file pointer appropriately. If the file cannot support positioning 
requests, or stream was opened with append mode, the character is appended to 
the output stream, putchar (c) is defined as putc(c, stdout). putc and 
putchar are macros. 

fputc behaves like putc, but is a fimction rather than a macro, fputc runs more 
slowly than putc, but it takes less space per invocation and its name can be 
passed as an argimient to a function. 

putw writes the word (i.e., integer) w to the output stream (where the file pointer, 
if defined, is pointing). The size of a word is the size of an integer and varies 
from machine to machine, putw neither assumes nor causes special alignment in 
the file. 

SEE ALSO 

exit(2), lseek(2), write(2), abort(3C), fclose(3S), ferror(3S), fopen(3S), 
f read(3S), printf (3S), puts(3S), setbuf (3S), stdio(3S). 

DIAGNOSTICS 

On success, these functions (with the exception of putw) each return the value 
they have written, putw returns f error (stream) . On failure, they return the 
constant EOF. This result will occur, for example, if the file stream is not open for 
writing or if the output file cannot grow. 

NOTES 

Because it is implemented as a macro, putc evaluates a stream argument more 
than once. In particular, putc(c, *f++); doesn't work sensibly, fputc should 
be used instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are machine-dependent, and may not be read using getw on a dif- 
ferent processor. 

Functions exist for all the above defined macros. To get the function form, the 
macro name must be undefined (e.g., #undef putc). 
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NAME 

putenv - change or add value to environment 

SYNOPSIS 

♦include <stdlib.h> 

int putenv (char * string) ; 
DESCRIPTION 

string points to a string of the form "name=value." putenv makes the value of the 
environment variable name equal to value by altering an existing variable or creat- 
ing a new one. In either case, the string pointed to by string becomes part of the 
environment, so altering the string will change the environment. The space used 
by string is no longer used once a new string-defining name is passed to putenv. 
Because of this limitation, string should be declared static if it is declared within a 
fimction. 

SEE ALSO 

exec(2), getenv(3C), xnalloc(3C), environ(5). 
DIAGNOSTICS 

putenv returns non-zero if it was unable to obtain enough space via malice for 
an expanded environment, otherwise zero. 

NOTES 

putenv manipulates the environment pointed to by environ, and can be used in 
conjunction with getenv. However, envp (the third argument to main) is not 
changed. 

This routine uses nvalloc(3C) to enlarge the environment. 

After putenv is called, environmental variables are not in alphabetical order. A 
potential error is to call the function putenv with a pointer to an automatic vari- 
able as the argument and to then exit the calling function while string is still part 
of the environment. 
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NAME 

putp%*ent ~ write password file entry 

SYNOPSIS 

♦include <pwd.h> 

int putpwent (const struct passwd *p, Fll£ 'ff) ; 
DESCRIPTION 

putpwent is the inverse of getpwent(3C). Given a pointer to a passwd structure 
created by getpwent (or getpwid or getpwnam)/ putpwent writes a line on the 
stream /, which matches the format of /etc/passwd. 

SEE ALSO 

getpwent(3C). 

DIAGNOSTICS 

putpwent returns non-zero if an error was detected during its operation, other- 
wise zero. 
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NAME 

puts, fputs - put a string on a stream 

SYNOPSIS 

♦include <stdio.h> 

int puts (const char *s) ; 
int fputs (const char '•'s, FII£ * stream) ; 
DESCRIPTION 

puts writes the string pointed to by s, followed by a new-line character, to the 
standard output stream stdout [see introO)]. 

fputs writes the null-terminated string pointed to by s to the named output 
stream. 

Neither function writes the terminating null character. 
SEE ALSO 

exit(2), lseek(2), write(2), abort(3C), fcloseOS), ferrorOS), fopen(3S), 
f read(3S), printf(3S), putc(3S), stdio(3S). 

DIAGNOSTICS 

On success both routines return the number of characters written; otherwise they 
return EOF. 

NOTES 

puts appends a new-line character while fputs does not. 
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NAME 

qsort - quicker sort 

SYNOPSIS 

♦include <stdlib.h> 

void qsort (void* base, sizejt nel, sizejt width) , int (*coirpar) 
(const void const void *)); 

DESCRIPTION 

qsort is an implementation of the quicker-sort algorithm. It sorts a table of data 
in place. The contents of the table are sorted in ascending order according to the 
user-supplied comparison function. 

base points to the element at the base of the table, nel is the number of elements 
in the table, vndth specifies the size of each element in bytes, compar is the name 
of the comparison function, which is called with two arguments that point to the 
elements being compared. The function must return an integer less than, equal 
to, or greater than zero to indicate if the first argument is to be considered less 
than, equal to, or greater than the second. 

The contents of the table are sorted in ascending order according to the user sup- 
plied comparison function. 

SEE ALSO 

bsearch(3C), lsearch(3C), string(3C). 
sort(l) in the User's Reference Manual. 

NOTES 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

The relative order in the output of two items that compare as equal is unpredict- 
able. 
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NAME 

raise - send signal to program 

SYNOPSIS 

tinclude <signal.h> 

int raise (int sig) ; 

DESCRIPTION 

raise sends the signal sig to the executing program. 

raise returns zero if the operation succeeds. Otherwise, raise returns -1 and 
errno is set to indicate the error, raise uses kill to send the signal to the exe- 
cuting program: 

kill (getpid ( ) , sig) / 

See kill(2) for a detailed list of failure conditions. See signal(2) for a list of sig- 
nals. 

SEE ALSO 

getpid(2), kill(2), signal(2). 
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NAME 

rand, srand - simple random-number generator 

SYNOPSIS 

♦include <stdlib.h> 

int rand (void) ; 
void srand (unsigned int seed) ; 
DESCRIPTION 

32 

rand uses a multiplicative congruential random-number generator with period 2 
that returns successive pseudo-random numbers in the range from 0 to RAND_MAX 
(defined in stdlib.h). 

The function srand uses the argument seed as a seed for a new sequence of 
pseudo-random numbers to be returned by subsequent calls to the function rand. 
If the function srand is then called with the same seed value, the sequence of 
pseudo-random numbers will be repeated. If the fimction rand is called before 
any calls to srand have been made, the same sequence will be generated as when 
srand is first called with a seed value of 1. 

NOTES 

The spectral properties of rand are limited. drand48(3C) provides a much better, 
though more elaborate, random-number generator. 

SEE ALSO 

drand48(3C). 
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NAME 

remove - remove file 

SYNOPSIS 

♦include <stdio.h> 

int remove (const char *path) ; 
DESCRIPTION 

remove causes the file or empty directory whose name is the string pointed to by 
path to be no longer accessible by that name. A subsequent attempt to open that 
file using that name will fail, unless the file is created anew. 

For files, remove is identical to unlink. For directories, remove is identical to 
rmdir. 

See rmdir(2) and imlink(2) for a detailed list of failure conditions. 

SEE ALSO 

rmdir(2), unlink(2). 

RETURN VALUE 

Upon successful completion, remove returns a value of 0; otherwise, it returns a 
value of -1 and sets errno to indicate an error. 
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NAME 

rename - rename file 

SYNOPSIS 

tinclude <stdio.h> 

int rename (const char *old^ const char ♦new); 
DESCRIPTION 

rename causes the file whose name is the string pointed to by old to be known by 
the name given by the string pointed to by new. The file named old is no longer 
accessible by that name. If a file named by the string pointed to by new exists 
prior to the call to rename, rename fails. 

rename returns zero if the operation succeeds. Otherwise, rename returns -1 
and, if the file existed previously, it is still known by its original name. 

rename simply performs the following operations: 

link (old, new) ; 
imlink (old) ; 

[See link(2) and unlink(2) for a detailed list of failure conditions.] 

SEE ALSO 

link(2), imlink(2). 
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NAME 

scanf , f scanf , sscanf - convert formatted input 

SYNOPSIS 

tinclude <stdio.h> 

int scanf (const char * format, ...); 

int f scanf (FILE *stnn, const char * format, ...); 

int sscanf (const char *s, const char * format, ...); 

DESCRIPTION 

scanf reads from the standard input stream, stdin. 

f scanf reads from the stream strm. 
sscanf reads from the character string s. 

Each function reads characters, interprets them according to a format, and stores 
the results in its argimients. Each expects, as arguments, a control string, format, 
described below and a set of pointer arguments indicating where the converted 
input should be stored. If there are insufficient arguments for the format, the 
behavior is undefined. If the format is exhausted while arguments remain, the 
excess argimients are simply ignored. 

The control string usually contains conversion specifications, which are used to 
direct interpretation of input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) that, 
except in two cases described below, cause input to be read up to the 
next non-white-space character. 

2. An ordinary character (not %) that must match the next character of the 
input stream. 

3. Conversion specifications consisting of the character % or the character 
sequence %digits$, an optional assignment suppression character *, a 
decimal digit string that specifies an optional numerical maximum field 
width, an optional letter 1 (ell), L, or h indicating the size of the receiv- 
ing object, and a conversion code. The conversion specifiers d, i, and n 
should be preceded by h if the corresponding argument is a pointer to 
short int rather than a pointer to int, or by 1 if it is a pointer to 
long int. Similarly, the conversion specifiers o, u, and x should be 
preceded by h if the corresponding argument is a pointer to imsigned 
short int rather than a pointer to unsigned int, or by 1 if it is a 
pointer to unsigned long int. Finally, the conversion specifiers e, f, 
and g should be preceded by 1 if the corresponding argument is a 
pointer to double rather than a pointer to float, or by L if it is a 
pointer to long double. The h, 1, or L modifier is ignored with any 
other conversion specifier. 

A conversion specification directs the conversion of the next input field; the result 
is placed in the variable pointed to by the corresponding argument unless assign- 
ment suppression was indicated by the character *. The suppression of assign- 
ment provides a way of describing an input field that is to be skipped. An input 
field is defined as a string of non-space characters; it extends to the next 
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inappropriate character or until the maximum field width, if one is specified, is 
exhausted. For all descriptors except the character [ and the character c, white 
space leading an input field is ignored. 

Conversions can be applied to the nth argument in the argument list, rather than 
to the next unused argument. In this case, the conversion character % (see above) 
is replaced by the sequence %digits$ where digits is a decimal integer n, giving the 
position of the argument in the argument list. The first such argument, %1$, 
immediately follows format. The control string can contain either form of a 
conversion specification, i.e., % or %digits$, although the two forms cannot be 
mixed within a single control string. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argument must usually be of a restricted type. For a 
suppressed field, no pointer argument is given. The following conversion codes 
are valid: 

% A single % is expected in the input at this point; no assignment is done. 

d Matches an optionally signed decimal integer, whose format is the same as 
expected for the subject sequence of the strtol function with the value 10 
for the base argument. The corresponding argument should be a pointer 
to integer. 

u Matches an optionally signed decimal integer, whose format is the same as 
expected for the subject sequence of the strtoul fimction with the value 
10 for the base argument. The corresponding argument should be a 
pointer to unsigned integer. 

0 Matches an optionally signed octal integer, whose format is the same as 
expected for the subject sequence of the strtoul function with the value 8 
for the base argument. The corresponding argument should be a pointer 
to unsigned integer. 

X Matches an optionally signed hexadecimal integer, whose format is the 
same as expected for the subject sequence of the strtoul function with 
the value 16 for the base argimient. The corresponding argument should 
be a pointer to unsigned integer. 

1 Matches an optionally signed integer, whose format is the same as 
expected for the subject sequence of the strtol function with the value 0 
for the base argument. The corresponding argument should be a pointer 
to integer. 

n No input is consumed. The corresponding argument should be a pointer 
to integer into which is to be written the number of characters read from 
the input stream so far by the call to the function. Execution of a %n 
directive does not increment the assignment count returned at the comple- 
tion of execution of the function. 

e,f,g Matches an optionally signed floating point number, whose format is the 
same as expected for the subject string of the strtod function. The 
corresponding argument should be a pointer to floating. 
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s A character string is expected; the corresponding argument should be a 
character pointer pointing to an array of characters large enough to accept 
the string and a terminating \0, which will be added automatically. The 
input field is terminated by a white-space character. 

c Matches a sequence of characters of the number specified by the field 
width (1 if no field width is present in the directive). The corresponding 
argument should be a pointer to the initial character of an array large 
enough to accept the sequence. No null character is added. The normal 
skip over white space is suppressed. 

[ Matches a nonempty sequence of characters from a set of expected charac- 
ters (the scanset). The corresponding argument should be a pointer to the 
initial character of an array large enough to accept the sequence and a ter- 
minating null character, which will be added automatically. The conver- 
sion specifier includes all subsequent characters in the format string, up to 
and including the matching right bracket (] ). The characters between the 
brackets (the scanlist) comprise the scanset, imless the character after the 
left bracket is a circimiflex C"), in which case the scanset contains all char- 
acters that do not appear in the scanlist between the circumflex and the 
right bracket. If the conversion specifier begins with [] or l"^], the right 
bracket character is in the scanlist and the next right bracket character is 
the matching right bracket that ends the specification; otherwise the first 
right bracket character is the one that ends the specification. 

A range of characters in the scanset may be represented by the construct 
first " last; thus [0123456789] may be expressed [0-9]. Using this con- 
vention, first must be lexically less than or equal to last, or else the dash 
will stand for itself. The character - will also stand for itself whenever it is 
the first or the last character in the scanlist. To include the right bracket 
as an element of the scanset, it must appear as the first character (possibly 
preceded by a circumflex) of the scanlist and in this case it will not be 
syntactically interpreted as the closing bracket. At least one character 
must match for this conversion to be considered successful. 

p Matches an implementation-defined set of sequences, which should be the 
same as the set of sequences that may be produced by the %p conversion 
of the print f function. The corresponding argument should be a pointer 
to void. The interpretation of the input item is implementation-defined. If 
the input item is a value converted earlier during the same program exe- 
cution, the pointer that results shall compare equal to that value; other- 
wise, the behavior of the %p conversion is undefined. 

If an invalid conversion character follows the %, the results of the operation may 
not be predictable. 

The conversion specifiers E, G, and X are also valid and, under the -Xa and -Xc 
compilation modes [see cc(l)], behave the same as e, g, and k, respectively. 
Under the ~Xt compilation mode, E, G, and X behave the same as le, Ig, and Ix^ 
respectively. 
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Each function allows for detection of a language-dependent decimal point charac- 
ter in the input string. The decimal point character is defined by the program's 
locale (category LCJTOMERIC). In the "C" locale, or in a locale where the decimal 
point character is not defined, the decimal point character defaults to a period ( . ). 

The scanf conversion terminates at end of file, at the end of the control string, or 
when an input character conflicts with the control string. 

If end-of-file is encountered during input, conversion is terminated. If end-of-file 
occurs before any characters matching the current directive have been read (other 
than leading white space, where permitted), execution of the current directive ter- 
minates with an input failure; otjfierwise, unless execution of the current directive 
is terminated with a matching failure, execution of the following directive (if any) 
is terminated with an input failure. 

If conversion terminates on a conflicting input character, the offending input char- 
acter is left tmread in the input stream. Trailing white space (including new-line 
characters) is left unread unless matched by a directive. The success of literal 
matches and suppressed assignments is not directly determinable other than via 
the %n directive. 

EXAMPLES 

The call to the function scanf : 

int i, n; float x; char naine[50]; 
n « scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E-1 thonpson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name 
will contain thoiipsonXO. 

The call to the function scanf: 

int i; float x; char name[50]; 

(void) scanf ("%2d%f%*d %[0-9]", &i, &x, name); 

with the input line: 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip 0123, and place the characters 56\0 in name. 
The next character read from stdin will be a. 

SEE ALSO 

cc(l), printfOS), strtod(3C), strtol(3C), strtoul(3C). 
DIAGNOSTICS 

These routines return the number of successfully matched and assigned input 
items; this number can be zero in the event of an early matching failure between 
an input character and the control string. If the input ends before the first match- 
ing failure or conversion, EOF is returned. 
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NAME 

setbuf , setT^uf - assign buffering to a stream 

SYNOPSIS 

♦include <stdio.h> 

void setJDuf (FILE ♦stream, char ♦buf ) ; 

int setvbuf (FILE ♦stream, char ♦buf, int type, sizejt size) ; 
DESCRIPTION 

setbuf may be used after a stream [see intro(3)] has been opened but before it is 
read or written. It causes the array pointed to by buf to be used instead of an 
automatically allocated buffer. If buf is the NULL pointer input/output will be 
completely unbuffered. 

While there is no limititation on the size of the buffer, the constant BUFSIZ, 
defined in the <stdio.h> header file, is tjrpically a good buffer size: 

char buf [BOFSIZ]; 

set^^f may be used after a stream has been opened but before it is read or 
written, type determines how stream will be buffered. Legal values for type 
(defined in stdio . h) are: 

_IOFBF causes input /output to be fully buffered. 

_IOLBF causes output to be line buffered; the buffer will be flushed when a 
newline is written, the buffer is full, or input is requested. 

_IONBF causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used for buffering, 
instead of an automatically allocated buffer, size specifies the size of the buffer to 
be used. If input/output is unbuffered, buf and size are ignored. 

For a further discussion of buffering, see stdio(3S). 

SEE ALSO 

f open(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 
DIAGNOSTICS 

If an illegal value for type is provided, setvbuf returns a non-zero value. Other- 
wise, it returns zero. 

NOTES 

A common source of error is allocating buffer space as an "automatic" variable in 
a code block, and then failing to close the stream in the same block. 

Parts of buf will be used for internal bookkeeping of the stream and, therefore, 
buf will contain less than size bytes when fiiU. It is recommended that the 
automatically allocated buffer is used when using setvbuf. 
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NAME 

set jnp, longjitp - non-local goto 

SYNOPSIS 

♦include <setjirp.h> 

int set jnp (jit)p__buf env) ; 
void long jnp (jnp_buf env, int val); 
DESCRIPTION 

These functions are useful for dealing with errors and interrupts encountered in a 
low-level subroutine of a program. 

set jnp saves its stack environment in env (whose type, jfnpjsuf, is defined in the 
<set jnp.h> header file) for later use by long jnp. It returns the value 0. 

long jnp restores the environment saved by the last call of set jnp with the 
corresponding env argument. After longjnp is completed, program execution 
continues as if the corresponding call of set jnp had just returned the value val. 
(The caller of set jnp must not have returned in the interim.) longjnp cannot 
cause set jnp to return the value 0. If longjnp is invoked with a second argu- 
ment of 0, set jnp will return 1. At the time of the second return from set jnp, 
all external and static variables have values as of the time longjnp is called (see 
example). The values of register and automatic variables are undefined. 

Register or automatic variables whose value must be relied upon must be 
declared as volatile. 

EXAMPLE 

♦include <stdio.h> 
♦include <stdlib.h> 
♦include <setjnp.h> 

jnpjDuf env; 
int i = 0; 
main () 
{ 

void exit ( ) ; 

if (set jnp (env) != 0) { 

(void) printf ("value of i on 2nd return from set jnp: %d\n", i) ; 
exit (0) ; 

) 

(void) printf ("value of i on 1st return from set jnp: %d\n", i) ; 

i = 1; 

gO; 

/+NOTREACHED*/ 

} 

go 
{ 

longjnp (env, 1) ; 

/♦NOTREACHED*/ 

} 
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If the a . out resulting from this C language code is run, the 
output will be: 

value of i on 1st return from setjnp:0 

value of i on 2nd return from setjnp:l 

SEE ALSO 

signal(2). 

NOTES 

If longjitp is called even though env was never primed by a call to set jitp, or 
when the last such call was in a function that has since returned, absolute chaos 
is guaranteed. 
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NAME 

setlcxi^ile - modify and query a program's locale 

SYNOPSIS 

tinclude <locale.h> 

char * setlocale (int category, const char * locale) ; 
DESCRIPTION 

setlocale selects the appropriate piece of the program's locale as specified by 
the category and locale arguments. The category argimient may have the following 
values: LCJCTYPE, LCJIUMERIC, LCJTIME, LC_OOLLATE, LCJiONETARY, and 
LC_ALL. These names are defined in the locale. h header file. LC_CTYPE affects 
the behavior of the character handling fimctions (isdigit, tolower, etc.) and the 
multibyte character functions (such as rrbtowc and wctoitib). LC__NUMERIC affects 
the decimal-point character for the formatted input /output functions and the 
string conversion functions as well as the non-mandatory formatting information 
returned by localeconv. [See localeconv(3C).] LC_TIME affects the behavior of 
ascftime, cftime, getdate and strftine. LCjCOLLATE affects the behavior of 
strcoll and strxf rm. LC_MONETARY affects the monetary formatted information 
returned by localeconv. LC_ALL names the program's entire locale. 

Each category corresponds to a set of databases which contain the relevant infor- 
mation for each defined locale. The location of a database is given by the follow- 
ing path, /u3r/liX>/ locale/locale /category, where locale and category are the 
names of locale and category, respectively. For example, the database for the 
LC_CTYPE category for the "german" locale would be found in 
/usr/lib/locale/german/LCjCTYPE. 

A value of "C" for locale specifies the default environment. 

A value of for locale specifies that the locale should be taken from environment 
variables. The order in which the environment variables are checked for the vari- 
ous categories is given below: 

Category 1st Env. Var. 2nd Env. Var 

LC_CTYPE: LCjCTYPE LANG 

LCJCOLLATE: LCjCOLLATE LANG 

LCjriME: LC_TIME LANG 

LCJMOMERIC: LCJIUMERIC LANG 

LC_MONETARY: LCJ40NETARY LANG 

At program startup, the equivalent of 

setlocale (LC_ALL, "C") 

is executed. This has the effect of initializing each category to the locale 
described by the environment "C". 

If a pointer to a string is given for locale, setlocale attempts to set the locale for 
the given category to locale. If setlocale succeeds, locale is returned. If setlo- 
cale fails, a null pointer is returned and the program's locale is not changed. 
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For category LC_AIjL, the behavior is slightly different. If a pointer to a string is 
given for bcale and LC^ALL is given for category, setlocale attempts to set the 
locale for all the categories to locale. The locale may be a simple locale, consisting 
of a single locale, or a composite locale. A composite locale is a string beginning 
with a "/" followed by the locale of each category separated by a "/". If 
setlocale fails to set the locale for any category, a null pointer is returned and 
the program's locale for all categories is not changed. Otherwise, locale is 
returned. 

A null pointer for locale causes setlocale to return the current locale associated 
with the category. The program's locale is not changed. 

FILES 

/usr/lib/locale/C/LC_CTYPE ~ LCjCTYPE database for the C locale. 
/usr/lib/locale/C/LC_NUMERIC - LC_NUMERIC database for the C locale. 
/usr/lib/locale/C/LC_TIME - LCJTIME database for the C locale. 
/usr/lib/locale/C/LC_OOLLATE - LCjOOLLATE database for the C locale. 
/usr/lih/ locale/locale /category - files containing the locale specific information 
for each locale and category. 

SEE ALSO 

ctixne(3C), ctype(3C), getdate(3C), localeconv(3C), ntotowc(3C), printf(3S), 
strcoll(3C), strftiine(3C), strtod(3C), strxfrm(3C), wctcaiib(3C), environ(5). 
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NAME 

sleep - suspend execution for interval 

SYNOPSIS 

tinclude <unistd.h> 

unsigned sleep (unsigned seconds) ; 
DESCRIPTION 

The current process is suspended from execution for the number of seconds 
specified by the argument. The actual suspension time may be less than that 
requested because any caught signal will terminate the sleep following execution 
of that signal's catching routine. Also, the suspension time may be longer than 
requested by an arbitrary amount because of the scheduling of other activity in 
the system. The value returned by sleep will be the "unslept" amoimt (the 
requested time minus the time actually slept) in case the caller had an alarm set 
to go off earlier than the end of the requested sleep time, or premature arousal 
because of another caught signal. 

The routine is implemented by setting an alarm signal and pausing until it (or 
some other signal) occurs. The previous state of the alarm signal is saved and 
restored. The calling program may have set up an alarm signal before calling 
sleep. If the sleep time exceeds the time until such alarm signal, the process 
sleeps only until the alarm signal would have occurred. The caller's alarm catch 
routine is executed just before the sleep routine returns. But if the sleep time is 
less than the time till such alarm, the prior alarm time is reset to go off at the 
same time it would have without the intervening sleep. 

SEE ALSO 

alanti(2), pause(2), signal(2), wait(2). 
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NAME 

ssignal, gsignal - software signals 

SYNOPSIS 

♦include <signal.h> 

int (♦ssignal (int sig, int (^action) (int) ) ) (int) ; 
int gsignal (int sig) ; 
DESCRIPTION 

ssignal and gsignal implement a software facility similar to signal(2). This 
facility is made available to users for their own purposes. 

Software signals made available to users are associated with integers in the 
inclusive range 1 through 17. A call to ssignal associates a procedure, action, 
with the software signed sig; the software signal, sig, is raised by a call to gsig- 
nal. Raising a software signal causes the action established for that signal to be 
taken. 

The first argument to ssignal is a number identifying the type of signal for 
which an action is to be established. The second argument defines the action; it is 
either the name of a (user-defined) action function or one of the manifest constants 
SIGJDFL (default) or SIG_IGN (ignore), ssignal returns the action previously 
established for that signal type; if no action has been established or the signal 
number is illegal, ssignal returns SIGJDFL. 

gsignal raises the signal identified by its argument, sig: 

If an action fimction has been established for sig, then that action is reset to 
SIG_J)FL and the action function is entered with argument sig. gsignal 
returns the value returned to it by the action function. 

If the action for sig is SIG__IGN, gsignal returns the value 1 and takes no 
other action. 

If the action for sig is SIGJDFL, gsignal returns the value 0 and takes no 
other action. 

If sig has an illegal value or no action was ever specified for sig, gsignal 
returns the value 0 and takes no other action. 

SEE ALSO 

signal(2), sigset(2), raise(3C). 
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NAME 

stdio - standard buffered input/output package 

SYNOPSIS 

♦include <stdio.h> 

FILE ♦stdin, ♦stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this manual constitute an 
efficient, user-level I/O buffering scheme. The in-line macros getc and putc han- 
dle characters quickly. The macros getchar and putchar, and the higher-level 
routines fgetc, fgets, ^rintf, fputc, fputs, fread, fscanf, fwrite, gets, 
getw, printf , puts, putw, and scanf all use or act as if they use getc and putc; 
they can be freely intermixed. 

A file with associated buffering is called a stream [see intro(3)] and is declared to 
be a pointer to a defined type FILE, fopen creates certain descriptive data for a 
stream and returns a pointer to designate the stream in all further transactions. 
Normally, there are three open streams with constant pointers declared in the 
<stdio.h> header file and associated with the standard open files: 

stdin standard input file 
stdout standard output file 
stderr standard error file 

The following symbolic values in <unistd.h> define the file descriptors that will 
be associated with the C-language stdin, stdout and stderr when the application is 
started: 

STDINJFILENO Standard input value, stdin. It has the value of 0. 
STDOOT_FILENO Standard output value, stdout. It has the value of 1. 
STDERRJFILENO Standard error value, stderr. It has the value of 2. 

A constant null designates a null pointer. 

An integer-constant EOF (~1) is returned upon end-of-file or error by most integer 
functions that deal with streams (see the individual descriptions for details). 

An integer constant BUFSIZ specifies the size of the buffers used by the particular 
implementation. 

An integer constant FILENAME_MAX specifies the size needed for an array of char 
large enough to hold the longest file name string that the implementation guaran- 
tees can be opened. 

An integer constant FOPEN_MAX specifies the minimum number of files that the 
implementation guarantees can be open simultaneously. Note that no more than 
255 files may be opened via fopen, and only file descriptors 0 through 255 are 
valid. 

Any program that uses this package must include the header file of pertinent 
macro definitions, as follows: 

♦include <stdio.h> 
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The functions and constants mentioned in the entries of sub-class 3S of this 
manual are declared in that header file and need no further declaration. The con- 
stants and the following "functions" are implemented as macros (redeclaration of 
these names is perilous): getc, getchar, putc, putchar, ferror, feof, clear- 
err, and fileno. There are also function versions of getc, getchar, putc, 
putchar, ferror, feof, clearerr, and fileno. 

Output streams, with the exception of the standard error stream stderr, are by 
default buffered if the output refers to a file and line-buffered if the output refers 
to a terminal. The standard error output stream stderr is by default unbuffered, 
but use of freopen [see fopen(3S)l will cause it to become buffered or line- 
buffered. When an output stream is unbuffered, information is queued for writ- 
ing on the destination file or terminal as soon as written; when it is buffered, 
many characters are saved up and written as a block. When it is 
line-buffered, each line of output is queued for writing on the destination termi- 
nal as soon as the line is completed (that is, as soon as a new-line character is 
written or terminal input is requested), setbuf or set^^uf [both described in 
setbuf (3S)] may be used to change the stream's buffering strategy. 

SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermidOS), 
cuseridOS), fclose(3S), ferror(3S), fopen(3S), f read(3S), f seek(3S), getc(3S), 
gets(3S), popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), 
systein(3S), t:iipf ile(3S), tii¥>naxi)(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers usually cause grave disorder, possibly including program 
termination. Individual function descriptions describe the possible error condi- 
tions. 
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NAME 

stdipc; f tok - standard interprocess communication package 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ipc.h> 

key_t f tok (const char ♦path, int id) ; 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be 
used by the xnsgget(2), semget(2), and shmget(2) system calls to obtain interpro- 
cess communication identifiers. One suggested method for forming a key is to 
use the ftok subroutine described below. Another way to compose keys is to 
include the project ID in the most significant byte and to use the remaining por- 
tion as a sequence ntmiber. There are many other ways to form keys, but it is 
necessary for each system to define standards for forming them. If some stan- 
dard is not adhered to, it will be possible for unrelated processes to imintention- 
ally interfere with each other's operation. It is still possible to interface intention- 
ally. Therefore, it is strongly suggested that the most significant byte of a key in 
some sense refer to a project so that keys do not conflict across a given system. 

ftok returns a key based on path and id that is usable in subsequent msgget, 
semget, and shmget system calls, path must be the path name of an existing file 
that is accessible to the process, is a character that imiquely identifies a project. 
Note that ftok will return the same key for linked files when called with the 
same id and that it will return different keys when called with the same file name 
but different ids. 

SEE ALSO 

intro(2), xnsgget(2), semget(2), shniget(2). 
DIAGNOSTICS 

ftok returns (key_t) -1 if path does not exist or if it is not accessible to the pro- 
cess. 

NOTES 

If the file whose path is passed to ftok is removed when keys still refer to the 
file, future calls to ftok with the same path and id will return an error. If the 
same file is recreated, then ftok is likely to return a different key than it did the 
original time it was called. 
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NAME 

strcoll - string collation 

SYNOPSIS 

# include <string.h> 

int strcoll (const char *sl, const char ♦s2); 
DESCRIPTION 

strcoll returns an integer greater than, equal to, or less than zero in direct 
correlation to whether string si is greater than, equal to, or less than the string s2. 
The comparison is based on strings interpreted as appropriate to the program's 
locale for category LC^COLLATE [see setlocale(3C)]. 

Both strcoll and strxf rm provide for locale-specific string sorting, strcoll is 
intended for applications in which the number of comparisons per string is small. 
When strings are to be compared a number of times, strxf rm is a more appropri- 
ate utility because the transformation process occurs only once. 

FILES 

/usr/lib/locale//ocaZe/LCjCOLLATE LCjCOLLATE database for locale. 
SEE ALSO 

colltbl(lM), setlocale(3C), string(3C), strxfnnOC), environ(5). 
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strerror - get error message string 

SYNOPSIS 

♦include <string.h> 

char * strerror (int ermum) ; 
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DESCRIPTION 

strerror maps the error number in errnum to an error message string, and 
returns a pointer to that string, strerror uses the same set of error messages as 
perror. The returned string should not be overwritten. 

SEE ALSO 

perror(3C). 
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NAME 

strftime, cftime, ascftime, - convert date and time to string 

SYNOPSIS 

♦include <tiit»e.h> 

sizejt *strftime (char size_t maxsize^ 

const char * format ^ const struct tm *timeptr) ; 

int cftime (char *s, char * format, const time_t *clock) ; 

int ascftime (char ^s, const char ^format, 

const struct tm *timeptr) ; 

DESCRIPTION 

strftime, ascftime and cftime place characters into the array pointed to by s 
as controlled by the string pointed to by format. The format string consists of zero 
or more directives and ordinary characters. All ordinary characters (including the 
terminating null character) are copied imchanged into the array. For strftime, 
no more than maxsize characters are placed into the array. 

If format is (char *)0, then the locale's default format is used. For strftime the 
default format is the same as "%c", for cftime and ascftime the default format 
is the same as "%C". cftime and ascftime first try to use the value of the 
environment variable CFTIME, and if that is undefined or empty, the default for- 
mat is used. 

Each directive is replaced by appropriate characters as described in the following 
list. The appropriate characters are determined by the LCJTIME category of the 
program's locale and by the values contained in the structure pointed to by 
timeptr for strftime and ascftime, and by the time represented by clock for 
cftime. 



%% same as % 

%a locale's abbreviated weekday name 

%A locale's full weekday name 

%b locale's abbreviated month name 

%B locale's full month name 

%c locale's appropriate date and time representation 

%C locale's date and time representation as produced by dated) 

%d day of month ( 01 - 31 ) 

%D date as %m/%d/%y 

%e day of month (1-31; single digits are preceded by a blank) 

%h locale's abbreviated month name. 

%H hour ( 00 - 23 ) 

%I hour ( 01 - 12 ) 

% j day number of year ( 001 - 366 ) 

%m month number ( 01 - 12 ) 

%M minute ( 00 * 59 ) 

%n same as Nn 

%p locale's equivalent of either AM or PM 
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%r 
%R 
%S 
%t 
%T 
%U 
%w 
%W 
%x 
%X 

%y 

%Y 
%Z 



time as %I:%M:%S [AM|PM] 
time as %H:%M 

seconds ( 00 - 61 ), allows for leap seconds 

insert a tab 

time as %H:%M:%S 

week number of year (00-53 ), Sunday is the first day of week 1 
weekday number ( 0 - 6 ), Simday = 0 

week number of year (00-53 ), Monday is the first day of week 1 
locale's appropriate date representation 
locale's appropriate time representation 
year within century ( 00 - 99 ) 
year as ccyy ( e.g. 1986) 

time zone name or no characters if no time zone exists 



The difference between %U and %W lies in which day is counted as the first of the 
week. Week number 01 is the first week in January starting with a Simday for %U 
or a Monday for %W. Week number 00 contains those days before the first Sun- 
day or Monday in January for %U and %W, respectively. 

If the total number of resulting characters including the terminating null character 
is not more than maxsize, strftiitie, cftime and ascftiine return the number of 
characters placed into the array pointed to by s not including the terminating null 
character. Otherwise, zero is returned and the contents of the array are indeter- 
minate, cftime and ascftime return the mmiber of characters placed into the 
array pointed to by s not including the terminating null character. 

Selecting the Output's Language 

By default, the output of strftime, cftime, and ascftime appear in US English. 
The user can request that the output of strftime, cftime or ascftime be in a 
specific language by setting the locale for category LCJTIME in setlcx:ale. 



The timezone is taken from the environment variable TZ [see ctime(3C) for a 
description of TZl. 

EXAMPLES 

The example illustrates the use of strftime. It shows what the string in str 
would look like if the structure pointed to by tmptr contains the values 
corresponding to Thursday, August 28, 1986 at \T,AA','^ in New Jersey. 



This results in str containing "Thursday Aug 28 240". 

FILES 

/usr/lib/locale/Iocak/LCjriME - file, containing locale specific date and time 
information 

SEE ALSO 

ctime(3C), getenv(3C), setlocale(3C), strftime(4), timezone(4), environ(5). 

NOTE 

cftime and ascftime are obsolete, strftime should be used instead. 
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NAME 

string; strcat, strdi:qp, strncat, strcnp, strncarp, strqpy, strnqpy, strlen, 
strchr, strrchr, strpbrk, strspn, strcsprv strtok;, strstr - string opera- 
tions 

SYNOPSiS 

♦include <string.h> 

char ♦strcat (char *sl, const char ♦s2) ; 
char '•'strdi:^ (const char *sl); 

char *strncat (char *sl, const char *a2, size_t n) ; 
int strcnp (const char *sl, const char *s2) ; 
int strncmp (const char ♦si, const char *s2, size_t n) ; 
char *strcpy (char ♦si, const char ♦s2) ; 
char ♦strncpy (char ♦si, const char ♦s2, size_t n) ; 
sizejt strlen (const char ♦s) ; 
char ♦strchr (const char ♦s, int c) ; 
char ♦strrchr (const char ♦s, int c) ; 
char ♦strpbrk (const char ♦si, const char ♦s2) ; 
sizejb strspn (const char ♦si, const char ♦s2) ; 
sizejb strcspn (const char ♦si, const char ♦s2); 
char ♦strtok (char ♦si, const char ♦s2) ; 
char ♦strstr (const char ♦si, const char ♦s2) ; 
DESCRIPTiON 

The arguments s, si, and s2 point to strings (arrays of characters terminated by a 
null character). The functions strcat, strncat, strcpy, strncpy, and strtok. 
all alter si. These fimctions do not check for overflow of the array pointed to by 
si. 

strcat appends a copy of string s2, including the terminating null character, to 
the end of string si. strncat appends at most n characters. Each returns a 
pointer to the null-terminated result. The initial character of s2 overrides the null 
character at the end of si. 

strcnp compares its arguments and returns an integer less than, equal to, or 
greater than 0, based upon whether si is lexicographically less than, equal to, or 
greater than s2. strncarp makes the same comparison but looks at at most n 
characters. Characters following a null character are not compared. 

strcpy copies string s2 to si including the terminating null character, stopping 
after the null character has been copied, strncpy copies exactly n characters, 
truncating s2 or adding null characters to si if necessary. The result will not be 
null-terminated if the length of s2 is n or more. Each fimction retums si . 
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strdup returns a pointer to a new string which is a duplicate of the string 
pointed to by si. The space for the new string is obtained using mallocOC). If 
the new string can not be created, a NULL pointer is returned. 

strlen returns the number of characters in s, not including the terminating null 
character. 

strchr (or strrchr) returns a pointer to the first (last) occurrence of c (con- 
verted to a char) in string s, or a NULL pointer if c does not occur in the string. 
The null character terminating a string is considered to be part of the string. 

strpbrk returns a pointer to the first occurrence in string si of any character 
from string s2, or a NULL pointer if no character from s2 exists in si . 

strspn (or strcspn) returns the length of the initial segment of string si which 
consists entirely of characters from (not from) string s2 . 

strtok considers the string si to consist of a sequence of zero or more text 
tokens separated by spans of one or more characters from the separator string s2 . 
The first call (with pointer si specified) returns a pointer to the first character of 
the first token, and will have written a null character into si immediately follow- 
ing the returned token. The fimction keeps track of its position in the string 
between separate calls, so that subsequent calls (which must be made with the 
first argument a NULL pointer) will work through the string si immediately fol- 
lowing that token. In this way subsequent calls will work through the string si 
until no tokens remain. The separator string s2 may be different from call to call. 
When no token remains in si, a NULL pointer is returned. 

strstr locates the first occurrence in string si of the sequence of characters 
(excluding the terminating null character) in string s2. strstr returns a pointer 
to the located string, or a null pointer if the string is not foimd. If s2 points to a 
string with zero length (i.e., the string ""), the function returns si. 

SEE ALSO 

mallocOC), setlocale(3C), strxfrn<3C). 

NOTES 

All of these functions assume the default locale "C." For some locales, strxf rm 
should be applied to the strings before they are passed to the fimctions. 
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NAME 

strtod, atof , convert string to double-precision number 

SYNOPSIS 

♦include <stdlib.h> 

doiable strtod (const char *nptr, char ♦*en<^ptr); 
double atof (const char ♦nptr) ; 
DESCRIPTION 

strtod returns as a double-precision floating-point number the value represented 
by the character string pointed to by nptr. The string is scanned up to the first 
unrecognized character. 

strtod recognizes an optional string of "white-space" characters [as defined by 
isspace in ctype(3C)], then an optional sign, then a string of digits optionally 
containing a decimal point character, then an optional exponent part including an 
e or E followed by an optional sign, followed by an integer. 

If the value of endptr is not (char ♦*)NULL, a pointer to the character terminat- 
ing the scan is returned in the location pointed to by endptr. If no number can be 
formed, *endptr is set to nptr, and zero is returned. 

atof (nptr) is equivalent to: 

strtod (nptr, (char **)NULL). 

SEE ALSO 

ctypeOC), scanfOS), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, IHCJGE is returned (according to the 
sign of the value), and ermo is set to ERANGE. 

If the correct value would cause underflow, zero is returned and ermo is set to 
ERANGE. 

When the -Xc or -Xa compilation options are used, HUGEJVAL is returned instead 
of HUGE. 
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NAME 

strtol, strtoul, atol, atoi - convert string to integer 

SYNOPSIS 

♦include <stdlib.h> 

long strtol (const char ♦str, char **ptr^ int base) ; 
unsigned long strtoul (const char *str, char **ptr, int base) ; 
long atol (const char *str) ; 
int atoi (const char *str) ; 
DESCRIPTION 

strtol returns as a long integer the value represented by the character string 
pointed to by str. The string is scanned up to the first character inconsistent 
with the base. Leading "white-space" characters [as defined by isspace in 
ctypeOOl are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating 
the scan is returned in the location pointed to by ptr. If no integer can be 
formed, that location is set to str, and zero is returned. 

If base is positive (and not greater than 36), it is used as the base for conversion. 
After an optional leading sign, leading zeros are ignored, and "Ox" or "OX" is 
ignored if base is 16. 

If base is zero, the string itself determines the base as follows: After an optional 
leading sign a leading zero indicates octal conversion, and a leading "Ox" or "OX" 
hexadecimal conversion. Otherwise, decimal conversion is used. 

Truncation from long to int can, of course, take place upon assignment or by an 
explicit cast. 

If the value represented by str would cause overflow, LONGJCOC or LONG__MIN is 
returned (according to the sign of the value), and ermo is set to the value, 
ERANGE. 

strtoul is similar to strtol except that strtoul returns as an unsigned long 
integer the value represented by str. If the value represented by str would cause 
overflow, UL0NGJ1AX is returned, and errno is set to the value, ERANGE. 

Except for behavior on error, atol (str) is equivalent to: strtol (str, (char 
**)NULL, 10). 

Except for behavior on error, atoi (str) is equivalent to: (int) strtol (str, 
(char ♦*)NULL, 10). 

DIAGNOSTICS 

If strtol is given a base greater than 36, it returns 0 and sets errno to EINVAL. 

SEE ALSO 

ctype(3C), scanf (3S), strtod(3C). 

NOTES 

strtol no longer accepts values greater than LONG_MAX as valid input. Use 
strtoul instead. 
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NAME 

strxfrm - string transformation 

SYNOPSIS 

♦include <string.h> 

sizejt strxfrm (char *sl, const char *a2, sizejt n) ; 
DESCRIPTION 

strxfrm transforms the string s2 and places the resulting string into the array si. 
The transformation is such that if strcnp is applied to two transformed strings, it 
will return the same result as strcoll applied to the same two original strings. 
The transformation is based on the program's locale for category LC_COLLATE 
[see setlocale(3C)]. 

No more than n characters will be placed into the resulting array pointed to by 
$1, including the terminating null character. If n is 0, then si is permitted to be a 
null pointer. If copying takes place between objects that overlap, the behavior is 
undefined. 

strxfrm returns the length of the transformed string (not including the terminat- 
ing null character). If the value returned is n or more, the contents of the array si 
are indeterminate. 

EXAMPLE 

The value of the following expression is the size of the array needed to hold the 
transformation of the string pointed to by s. 

1 + strxfrm (NULL, s, 0); 

FILES 

/usr/lib/locale//oca/g/LCjCOLLATE LCjCOLLATE database for locale. 
SEE ALSO 

colltbl(lM), setlocale(3C), strcoll(3C), string(3C), environ(5). 

DIAGNOSTICS 

On failure, strxfrm returns (size_t) -1. 
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NAME 

swab - swap bytes 

SYNOPSIS 

tinclude <8tdlib.h> 

void swab (const char *f rom^ char *to, int nbytes) ; 
DESCRIPTION 

swab copies nbytes bytes pointed to by from to the array pointed to by to, 
exchanging adjacent even and odd bytes, nbytes should be even and non- 
negative. If nbytes is odd and positive, swab uses nbytes- 1 instead. If nbytes is 
negative, swab does nothing. 
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NAME 

system - issue a shell command 

SYNOPSIS 

tinclude <stdlib.h> 

int system (const char * string) ; 
DESCRIPTION 

system causes the string to be given to the shell [see sh(l)] as input, as if the 
string had been typed as a command at a terminal. The current process waits 
until the shell has completed, then returns the exit status of the shell in the for- 
mat specified by wait. 

If string is a NULL pointer, system checks if /bin/sh exists and is executable. If 
/bin/sh is available, systan returns non-zero; otherwise it returns zero. 

system fails if one or more of the following are true: 

EAGAIN The system-imposed limit on the total number of processes under 
execution by a single user would be exceeded. 

EINTR system was interupted by a signal. 

ENOMEM The new process requires more memory than is allowed by the 
system-imposed maximum {MAXMEM}. 

SEE ALSO 

exec(2), wait(3C). 

sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

system forks to create a child process that in turn execs /bin/sh in order to exe- 
cute string. If the fork or exec fails, system returns a value of -1 and sets errno. 
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NAME 

tirpf ile - create a temporary file 

SYNOPSIS 

tinclude <stdio.h> 

FILE *tnpfile (void) ; 
DESCRIPTION 

tirpfile creates a temporary file using a name generated by the tnpnam routine 
and returns a corresponding FILE pointer. If the file cannot be opened, a NULL 
pointer is returned. The file is automatically deleted when the process using it 
terminates or when the file is closed. The file is opened for update ("w+"). 

SEE ALSO 

creat(2), ppen(2), unlink(2), fopenOS), mktenp(3C), perror(3C), stdio(3S), 
t:npnaxn(3S). 
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NAME 

tirpnanv texrpnam - create a name for a temporary file 

SYNOPSIS 

tinclude <stdio.h> 

char *t:irpnam (char *s) ; 

char ♦tenpnam (const char ♦dir^ const char *pfx) ; 
DESCRIPTION 

These functions generate file names that can safely be used for a temporary file. 

tirpnam always generates a file name using the path-prefix defined as P_tirpdir 
in the <stdio.h> header file. If s is NULL, tirpnam leaves its result in an internal 
static area and returns a pointer to that area. The next call to titpnam will des- 
troy the contents of the area. If s is not NULL, it is assumed to be the address of 
an array of at least L_titpnam bytes, where Ljbnpnam is a constant defined in 
<stdio.h>; tnpnam places its result in that array and returns s. 

tenpnam allows the user to control the choice of a directory. The argument dir 
points to the name of the directory in which the file is to be created. If dir is 
NULL or points to a string that is not a name for an appropriate directory, the 
path-prefix defined as P_tiipdir in the <stdio.h> header file is used. If that 
directory is not accessible, /tnp will be used as a last resort. This entire sequence 
can be up-staged by providing an environment variable TMPDIR in the user's 
environment, whose value is the name of the desired temporary-file directory. 

Many applications prefer their temporary files to have certain favorite initial letter 
sequences in their names. Use the pfx argument for this. This argument may be 
NULL or point to a string of up to five characters to be used as the first few char- 
acters of the temporary-file name. 

tenpnam uses roalloc to get space for the constructed file name, and returns a 
pointer to this area. Thus, any pointer value returned from tenpnam may serve 
as an argument to free [see roalloc(3C)]. If tenpnam cannot return the expected 
result for any reason — e.g., malloc failed — or none of the above mentioned 
attempts to find an appropriate directory was successful, a NULL pointer will be 
returned. 

tenpnam fails if there is not enough space. 

FILES 

P_tnpdir /usr/tnp 
SEE ALSO 

creat(2), unlink(2), f open(3S), malloc(3C), mktenp(3C), tnpf ile(3S). 

NOTES 

These functions generate a different file name each time they are called. 

Files created using these functions and either f open or creat are temporary only 
in the sense that they reside in a directory intended for temporary use, and their 
names are imique. It is the user's responsibility to remove the file when its use is 
ended. 
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If called more than TMP_MAX (defined in stdio . h) times in a single process, these 
functions start recycling previously used names. 

Between the time a file name is created and the file is opened, it is possible for 
some other process to create a file with the same name. This can never happen if 
that other process is using these fimctions or xnlctemp and the file names are 
chosen to render duplication by other means unlikely. 
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NAME 

tsearch, tf ind, tdelete, twalk - manage binary search trees 

SYNOPSIS 

tinclude <search.h> 

void *tsearch (const void *key^ void **rootp, int ("'conpar) 
(const void *, const void *)); 

void *tfind (const void *key, void * const *rootp^ int ('•'ccnpar) 
(const void const void *)); 

void *tdelete (const void *key^ void **rootp, int (*compar) 
(const void const void *)); 

void twalk (void *root, void(*action) (void VISIT, int)); 

DESCRIPTION 

tsearch, tfind, tdelete, and twalk are routines for manipulating binary 
search trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All 
comparisons are done with a user-supplied routine. This routine is called with 
two arguments, the pointers to the elements being compared. It returns an 
integer less than, equal to, or greater than 0, according to whether the first argu- 
ment is to be considered less than, equal to or greater than the second argument. 
The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

tsearch is used to build and access the tree, key is a pointer to a datum to be 
accessed or stored. If there is a datum in the tree equal to *key (the value 
pointed to by key), a pointer to this found datum is returned. Otherwise, *key is 
inserted, and a pointer to it returned. Only pointers are copied, so the calling 
routine must store the data, rootp points to a variable that points to the root of 
the tree. A NULL value for the variable pointed to by rootp denotes an empty tree; 
in this case, the variable will be set to point to the datimi which will be at the 
root of the new tree. 

Like tsearch, tf ind will search for a datum in the tree, returning a pointer to it 
if found. However, if it is not found, tf ind will return a NULL pointer. The 
argimients for tf ind are the same as for tsearch. 

tdelete deletes a node from a binary search tree. The arguments are the same 
as for tsearch. The variable pointed to by rootp will be changed if the deleted 
node was the root of the tree, tdelete returns a pointer to the parent of the 
deleted node, or a NULL pointer if the node is not found. 

twalk traverses a binary search tree, root is the root of the tree to be traversed. 
(Any node in a tree may be used as the root for a walk below that node.) action 
is the name of a routine to be invoked at each node. This routine is, in turn, 
called with three arguments. The first argument is the address of the node being 
visited. The second argument is a value from an enumeration data type typed^ 
enum { preorder, postorder, endorder, leaf } VISTT; (defined in the search. h header 
file), depending on whether this is the first, second or third time that the node 
has been visited (during a depth-first, left-to-right traversal of the tree), or 
whether the node is a leaf. The third argimient is the level of the node in the 
tree, with the root being level zero. 
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The pointers to the key and the root of the tree should be of type pointer-to- 
element, and cast to type pointer-to-character. Similarly, although declared as 
type pointer-to-character, the value returned should be cast into type pointer-to- 
element. 

EXAMPLE 

The following code reads in strings and stores structures containing a pointer to 
each string and a coimt of its length. It then walks the tree, printing out the 
stored strings and their lengths in alphabetical order. 

♦include <string.h> 
♦include <stdio.h> 
♦include <search.h> 

struct node { 

char *string; 
int length; 

}; 

char string_space [10000] ; 
struct node nodes [500]; 
void *root = NULL; 

int node__conpare (const void *nodel, const void *node2) { 
return strcnp (( (const struct node *) node l)->st ring, 
((const struct node *) node2) ->string) ; 

} 

void print_node (void **node, VISIT order , int level) { 
if (order = preorder I I order = leaf) { 
printf ("length=%d, string=%20s\n", 
(♦(struct node **)node) ->length, 
( * ( struct node * * ) node ) ->st ring) ; 

} 

} 

mainO { 

char *strptr » string_space; 
struct node *nodeptr = nodes; 
int i = 0; 

i^ile (gets(strptr) != NULL && i++ < 500) { 
nodeptr->string = strptr; 
nodeptr->length = strlen (strptr) ; 
(void) tsearch ( (void *)nodeptr, 
&root, node_conpare) ; 
strptr +« nc>deptr->length + 1; 
nodeptr++; 

> 

twalk ( root , pr int_nc>de ) ; 

} 
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SEE ALSO 

bsearchOC), hsearch(3C), IsearchOC). 

DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough space available to 
create a new node. 

A NULL pointer is returned by tf ind and tdelete if rootp is NULL on entry. 

If the datum is found, both tsearch and tf ind return a pointer to it. If not, 

tf ind returns NULL, and tsearch returns a pointer to the inserted item. 

NOTES 

The root argument to twalk is one level of indirection less than the rootp argu- 
ments to tsearch and tdelete. 

There are two nomenclatures used to refer to the order in which tree nodes are 
visited, tsearch uses preorder, postorder and endorder to refer respectively to 
visiting a node before any of its children, after its left child and before its right, 
and after both its children. The alternate nomenclature uses preorder, inorder 
and postorder to refer to the same visits, which could result in some confusion 
over the meaning of postorder. 

If the calling function alters the pointer to the root, results are unpredictable. 
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NAME 

ttyname, isatty - find name of a terminal 

SYNOPSIS 

♦include <stdlib.h> 

char *ttyna2ne (int f ildes) ; 
int isatty (int fildes) ; 
DESCRIPTION 

ttyname returns a pointer to a string containing the null-terminated path name of 
the terminal device associated with file descriptor fildes. 

isatty returns 1 if fildes is associated with a terminal device, 0 otherwise. 

FILES 

/dev/* 
DIAGNOSTICS 

ttynaxne returns a NULL pointer if fildes does not describe a terminal device in 
directory /dev. 

NOTES 

The return value points to static data whose content is overwritten by each call. 
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NAME 

ttyslot - find the slot in the utmp file of the current user 

SYNOPSIS 

tinclude <stdlib.h> 

int ttyslot (void); 
DESCRIPTION 

ttyslot returns the index of the current user's entry in the /etc/ut:irp file. The 
returned index is accomplished by scanning files in /dev for the name of the ter- 
minal associated with the standard input, the standard output, or the standard 
error output (0, 1, or 2). 

FILES 

/etc/utanp 

SEE ALSO 

getutOO, ttyname(3C). 

DIAGNOSTICS 

A value of -1 is returned if an error was encoimtered while searching for the ter- 
minal name or if none of the above file descriptors are associated with a terminal 
device. 
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NAME 

ungetc - push character back onto input stream 

SYNOPSIS 

♦include <stdio.h> 

int ungetc (int c, FILE * stream) ; 

DESCRIPTION 

ungetc inserts the character specified by c (converted to an unsigned char) into 
the buffer associated with an input stream [see intro(3)]. That character, c, will 
be returned by the next getc(3S) call on that stream, ungetc returns c, and 
leaves the file corresponding to stream unchanged. A successful call to ungetc 
clears the EOF indicator for stream. 

Four bytes of pushback are guaranteed. 

The value of the file position indicator for stream after reading or discarding all 
pushed-back characters will be the same as it was before the characters were 
pushed back. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 

f seek, rewind [both described on f seek(3S)], and f setpos erase the memory of 
inserted characters for the stream on which they are applied. 

SEE ALSO 

fseekOS), f setposOC), getc(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

ungetc returns EOF if it cannot insert the character. 
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NAME 

vprintf, vfprintf, vsprintf - print formatted output of a variable argument 
list 

SYNOPSIS 

iinclude <stdio.h> 
♦include <stdarg.h> 

int vprintf (const char * format, va_list ap) ; 
int vfprintf (FILE *siream, const char * format, va_list ap); 
int vsprintf (char *s, const char ^format, va_list ap) ; 
DESCRIPTION 

vprintf, vfprintf and vsprintf are the same as printf, fprintf, and 
sprintf respectively, except that instead of being called with a variable number 
of arguments, they are called with an argument list as defined by the <stdarg.h> 
header file. 

The <stdarg.h> header file defines the type va_list and a set of macros for 
advancing through a list of argimients whose number and t5rpes may vary. The 
argtiment ap to the vprint family of routines is of type va_list. This argument 
is used with the <stdarg.h> header file macros va start, va__arg and va_end 
[see va^stiart, va_arg, and vajend in stdarg(5)]. The EXAMPLE section below 
shows their use with vprintf. 

EXAMPLE 

The following demonstrates how vfprintf could be used to write an error rou- 
tine: 

iinclude <stdio.h> 
iinclude <stdarg.h> 
/* 

* error should be called like 

* error (function^name, format, argl, ...); 
*/ 

void error (char *fvinction__naine, char *fonnat, 
{ 

va_list ap; 

va_start (ap, format) ; 

/* print out name of function causing error */ 
(void) fprintf (stderr, "ERR in %s: functionjname) ; 
va_arg(ap, char*); 

/* print out remainder of message */ 
(void) vfprintf (stderr, format, ap) ; 
va__end(ap); 
(void) abort; 

> 
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SEE ALSO 

printfOS), stdarg(5). 

DIAGNOSTICS 

vprintf and vfprintf return the number of characters transmitted, or return -1 
if an error was encountered. 
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NAME 

elf - object file access library 

SYNOPSIS 

cc [flag .,.] file ... -lelf [library . . .] 

♦include <libelf .h> 

DESCRIPTION 

Functions in the ELF access library let a program manipulate ELF (Executable and 
Linking Format) object files, archive files, and archive members. The header file 
provides type and function declarations for all library services. 

Programs communicate with many of the higher-level routines using an ELF 
descriptor. That is, when the program starts working with a file, elf_begin 
creates an ELF descriptor through which the program manipulates the structures 
and information in the file. These ELF descriptors can be used both to read and 
to write files. After the program establishes an ELF descriptor for a file, it may 
then obtain section descriptors to manipulate the sections of the file [see 
elf__getscn(3E)]. Sections hold the bulk of an object file's real information, such 
as text, data, the symbol table, and so on. A section descriptor 'l^elongs" to a 
particular ELF descriptor, just as a section belongs to a file. Finally, data descrip- 
tors are available through section descriptors, allowing the program to manipulate 
the information associated with a section. A data descriptor "belongs" to a sec- 
tion descriptor. 

Descriptors provide private handles to a file and its pieces. In other words, a 
data descriptor is associated with one section descriptor, which is associated with 
one ELF descriptor, which is associated with one file. Although descriptors are 
private, they give access to data that may be shared. Consider programs that 
combine input files, using incoming data to create or update another file. Such a 
program might get data descriptors for an input and an output section. It then 
could update the output descriptor to reuse the input descriptor's data. That is, 
the descriptors are distinct, but they could share the associated data bytes. This 
sharing avoids the space overhead for duplicate buffers and the performance 
overhead for copying data unnecessarily. 

FILE CLASSES 

ELF provides a framework in which to define a family of object files, supporting 
multiple processors and architectures. An important distinction among object 
files is the class, or capacity, of the file. The 32-bit class supports architectures in 
which a 32-bit object can represent addresses, file sizes, etc., as in the following 
table. 
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Name 



Purpose 



unsigned char 



Elf32_Addr 
Elf32_Half 
Elf32j0ff 
Elf32_Sword 
Elf32 Word 



Unsigned address 
Unsigned medium integer 
Unsigned file offset 
Signed large integer 
Unsigned large integer 
Unsigned small integer 



Other classes will be defined as necessary, to support larger (or smaller) 
machines. Some library services deal only with data objects for a specific class, 
while others are class-independent. To make this distinction clear, library func- 
tion names reflect their status, as described below. 

DATA REPRESENTATIONS 

Conceptually, two parallel sets of objects support cross compilation environments. 
One set corresponds to file contents, while the other set corresponds to the native 
memory image of the program manipulating the file. Type definitions supplied 
by the header files work on the native machine, which may have different data 
encodings (size, byte order, etc.) than the target machine. Although native 
memory objects should be at least as big as the file objects (to avoid information 
loss), they may be bigger if that is more natural for the host machine. 

Translation facilities exist to convert between file and memory representations. 
Some library routines convert data automatically, while others leave conversion 
as the program's responsibility. Either way, programs that create object files 
must write file-t)rped objects to those files; programs that read object files must 
take a similar view. See elf_xlate(3E) and elf_f size(3E) for more informa- 
tion. 

Programs may translate data explicitly, taking full control over the object file lay- 
out and semantics. If the program prefers not to have and exercise complete con- 
trol, the library provides a higher-level interface that hides many object file 
details. elfj:>egin and related functions let a program deal with the native 
memory types, converting between memory objects and their file equivalents 
automatically when reading or writing an object file. 

ELF VERSIONS 

Object file versions allow ELF to adapt to new requirements. Three — 
independent — versions can be important to a program. First, an application pro- 
gram knows about a particular version by virtue of being compiled with certain 
header files. Second, the access library similarly is compiled with header files 
that control what versions it understands. Third, an ELF object file holds a value 
identifying its version, determined by the ELF version known by the file's creator. 
Ideally, all three versions would be the same, but they may differ. 

If a program's version is newer than the access library, the program 
might use information unknown to the library. Translation routines 
might not work properly, leading to undefined behavior. This condition 
merits installing a new library. 



Page 2 10/89 



elf(3E) 



elf(3E) 



The library's version might be newer than the program's and the file's. 
The library imderstands old versions, thus avoiding compatibility prob- 
lems in this case. 

Finally, a file's version might be newer than either the program or the 
library understands. The program might or might not be able to process 
the file properly, depending on whether the file has extra information 
and whether that information can be safely ignored. Again, the safe 
alternative is to install a new library that understands the fQe's version. 

To accommodate these differences, a program must use elf_yersion to pass its 
version to the library, thus establishing the xvorJdng version for the process. Using 
this, the library accepts data from and presents data to the program in the proper 
representations. When the library reads object files, it uses each file's version to 
interpret the data. When writing files or converting memory types to the file 
equivalents, the library uses the program's working version for the file data. 

SYSTEM SERVICES 

As mentioned above, elf_begin and related routines provide a higher-level 
interface to ELF files, performing input and output on behalf of the application 
program. These routines assume a program can hold entire files in memory, 
without explicitly using temporary files. When reading a file, the library routines 
bring the data into memory and perform subsequent operations on the memory 
copy. Programs that wish to read or write large object files with this model must 
execute on a machine with a large process virtual address space. If the imderly- 
ing operating system limits the number of open files, a program can use 
elf_jcntl to retrieve all necessary data from the file, allowing the program to 
close the file descriptor and reuse it. 

Although the elf_begin interfaces are convenient and efficient for many pro- 
grams, they might be inappropriate for some. In those cases, an application may 
invoke the elf_xlate data translation routines directly. These routines perform 
no input or output, leaving that as the application's responsibility. By assuming a 
larger share of the job, an application controls its input and output model. 

LIBRARY NAMES 

Names associated with the library take several forms. 

elfjtame These class-independent names perform some service, name, for 

the program. 

elf32jtame Service names with an embedded class, 32 here, indicate they 
work only for the designated class of files. 

Elf JType Data types can be class-independent as well, distinguished by 

Type, 

Elf 32_Type Class-dependent data types have an embedded class name, 32 
here. 

ELFjC__CMD Several functions take commands that control their actions. 

These values are members of the Elf__Cmd enumeration; they 
range from zero through ELF_C_NUM-1. 
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ELF_F__FLAG Several functions take flags that control library status and /or 
actions. Rags are bits that may be combined. 

ELF32_FSZ JTYPE 

These constants give the file sizes in bytes of the basic ELF types 
for the 32-bit class of files. See elf_fsize for more informa- 
tion. 

ELFJiJCIND The fimction elfjcind identifies the KIND of file associated 
with an ELF descriptor. These values are members of the 
Elf_Kind enimieration; they range from zero through 
ELF_KNUM-1. 

ElFJTjTfPE When a service function, such as elfjclate, deals with multi- 
ple types, names of this form specify the desired TYPE. Thus, 
for example, ELFJTJEHDR is directly related to Elf32JEhdr. 
These values are members of the Elf_Type enumeration; they 
range from zero through ELFjr_NUM-l. 

SEE ALSO 

cof2elf (1), elf J>egin(3E), elf_cntl(3E), elf_end(3E), elf jerror(3E), 
elf_f ill(3E), elf_f lag(3E), elf__f size(3E), elf_getarhdr(3E), 
elf_5etarsyni(3E), elf_getbase(3E), elf_getdata(3E), elf_getehdr(3E), 
elf jgetident(3E), elf_getphdr(3E), elf_getscn(3E), elf_getshdr(3E), 
elf Jiash(3E), elf_kind(3E), elf_next(3E), elf_rand(3E), elf_rawf ile(3E), 
elf_strptr(3E), elf_update(3E), elf_version(3E), elf_xlate(3E), a.out(4) 
ar(4) 

The "Object Files" in the chapter Programmer's Guide: ANSI C and Programming 
Support Tools. 

NOTES 

Information in the ELF header files is separated into common parts and 
processor-specific parts. A program can make a processor's information available 
by including the appropriate header file: <sys/elf_NAME . h> where NAME 
matches the processor name as used in the ELF file header. 



Symbol 


Processor 


M32 


AT&T WE 32100 


SPARC 


SPARC 


386 


Intel 80386 


486 


Intel 80486 


860 


Intel 80860 


68K 


Motorola 68000 


88K 


Motorola 88000 



Other processors will be added to the table as necessary. To illustrate, a program 
could use the following code to "see" the processor-specific information for the 
WE 32100. 

♦include <libelf.h> 
♦include <sys/elf__M32.h> 
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Without the <sys/elf_M32 . h> definition, only the common ELF information 
would be visible. 
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NAME 

elf_begin - make a file descriptor 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

tinclude <libelf .h> 

Elf *elf_begin(int fildes, Elf_Cmd cmd. Elf *ref ) ; 
DESCRIPTION 

elf jDegin, elf_next, elf_rand, and elf_end work together to process ELF 
object files, either individually or as members of archives. After obtaining an ELF 
descriptor from elfjDegin, the program may read an existing file, update an 
existing file, or create a new file, fildes is an open file descriptor that elf_begin 
uses for reading or writing. The initial file offset [see lseek(2)] is unconstrained, 
and the resulting file offset is undefined. 

cmd may have the following values. 

ELF_C_NULL When a program sets cmd to this value, elf^begin returns a 
null pointer, without opening a new descriptor, ref is ignored 
for this command. See elf__next(3E) and the examples below 
for more information. 

ELFjC_READ When a program wishes to examine the contents of an existing 
file, it should set cmd to this value. Depending on the value of 
ref, this command examines archive members or entire files. 
Three cases can occur. 

First, if ref is a null pointer, elf_begin allocates a new ELF 
descriptor and prepares to process the entire file. If the file 
being read is an archive, elf_begin also prepares the resulting 
descriptor to examine the initial archive member on the next call 
to elfjDegin, as if the program had used elf_next or 
elf__rand to "move" to the initial member. 

Second, if ref is a non-null descriptor associated with an archive 
file, elf_begin lets a program obtain a separate ELF descriptor 
associated with an individual member. The program should 
have used elf_next or elf_rand to position ref appropriately 
(except for the initial member, which elf_begin prepares; see 
the example below). In this case, fildes should be the same file 
descriptor used for the parent archive. 

Finally, if ref is a non-null ELF descriptor that is not an archive, 
elf_begin increments the number of activations for the 
descriptor and returns ref, without allocating a new descriptor 
and without changing the descriptor's read /write permissions. 
To terminate the descriptor for ref, the program must call 
elf__end once for each activation. See elf_next(3E) and the 
examples below for more information. 
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ELF_C__RDWR This command duplicates the actions of ELFjC_READ and addi- 
tionally allows the program to update the file image [see 
elf_update(3E)]. That is, using ELFjC^READ gives a read-only 
view of the file, while ELF_C_RDWR lets the program read and 
write the file. ELFjC_RDWR is not valid for archive members. If 
ref is non-null, it must have been created with the ELF_C_RDWR 
command. 

ELF__CJWRITE If the program wishes to ignore previous file contents, presum- 
ably to create a new file, it should set cmd to this value, ref is 
ignored for this command. 

elf_begin "works" on all files (including files with zero bytes), providing it can 
allocate memory for its internal structures and read any necessary information 
from the file. Programs reading object files thus may call elfjcind or 
elf jgetehdr to determine the file type (only object files have an ELF header). If 
the file is an archive with no more members to process, or an error occurs, 
elf_begin returns a null pointer. Otherwise, the return value is a non-null ELF 
descriptor. 

Before the first call to elf_begin, a program must call elf_yersion to coordi- 
nate versions. 

SYSTEM SERVICES 

When processing a file, the library decides when to read or write the file, depend- 
ing on the program's requests. Normally, the library assumes the file descriptor 
remains usable for the life of the ELF descriptor. If, however, a program must 
process many files simultaneously and the underl)dng operating system limits the 
number of open files, the program can use elf jcntl to let it reuse file descrip- 
tors. After calling elf jcntl with appropriate arguments, the program may close 
the file descriptor without interfering with the library. 

All data associated with an ELF descriptor remain allocated until elf_end ter- 
minates the descriptor's last activation. After the descriptors have been ter- 
minated, the storage is released; attempting to reference such data gives 
undefined behavior. Consequently, a program that deals with multiple input (or 
output) files must keep the ELF descriptors active until it finishes with them. 

EXAMPLES 

A prototype for reading a file appears below. If the file is a simple object file, the 
program executes the loop one time, receiving a null descriptor in the second 
iteration. In this case, both elf and arf will have the same value, the activation 
count will be two, and the program calls elfjend twice to terminate the descrip- 
tor. If the file is an archive, the loop processes each archive member in turn, 
ignoring those that are not object files. 
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if (elf_version(EVjCURRENT) — EVNONE) 
{ 

/* library out of date ♦/ 
/* recover from error */ 

} 

cmd = ELFJC_READ; 

arf « elfjDegin(fildes, and, (Elf *)0); 

while ((elf - elf jDegin(fildes, cand, arf)) !« 0) 

{ 

if ((ehdr - elf 32_getehdr (elf ) ) != 0) 
{ 

/* process the file . . . ♦/ 

} 

and » elf_next (elf) ; 
elf_end(elf); 

} 

elf_end (arf) ; 

Alternatively, the next example illustrates random archive processing. After iden- 
tifying the file as an archive, the program repeatedly processes archive members 
of interest. For clarity, this example omits error checking and ignores simple 
object files. Addition^ly, this fragment preserves the ELF descriptors for all 
archive members, because it does not call elf__end to terminate them. 

elf_version(EV_CURRENT) ; 

arf = elfj)egin(fildes, ELFj:__READ, (Elf *)0); 

if (elf_kind(arf) != ELF_KAR) 

{ 

/♦ not an archive */ 

) 

/* initial processing */ 

/'f set offset s ... for desired ineni>er header */ 

while (elf_rand (eu:f , offset) ~ offset) 

{ 

if ((elf = elfj>egin(fildes, ELFJC_READ, arf)) == 0) 
break; 

if ((ehdr = elf 32_getehdr (elf ) ) != 0) 
{ 

/* process archive meirber . . . ♦/ 

} 

/* set offset «... for desired meirber header */ 

} 

The following outline shows how one might create a new ELF file. This example 
is simplified to show the overall flow. 
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elf _yers ion (EV__CURRENT) ; 

fildes = open ("path/name", 0_RDWR|0_TRUNC|0_CREAT, 0666); 
if ((elf = elf_begin (fildes, ELFjCJWRITE, (Elf *)0)) ~ 0) 

return; 
ehdr = elf 32_newehdr (elf ) ; 
phdr = elf32_ne%*phdr(elf, count); 
sen = elf__newscn(elf) ; 
shdr = elf32_getshdr(scn) ; 
data - elf_newdata (sen) ; 
elfjapdate(elf, ELF_C_WRITE) ; 
elf_end(elf); 

Finally, the following outline shows how one might update an existing ELF file. 
Again, this example is simplified to show the overall flow. 

elf_version (EV_CURRENT) ; 

fildes « open ("path/name", 0_RDWR) ; 

elf » elf J>egin (fildes, ELFJC_RDWR, (Elf *)0); 

/* add new or delete old information ... */ 

close (creat ( "path/name" , 0666)); 
elf_update(elf, ELF_C_WRITE) ; 
elf_end(elf); 

In the example above, the call to creat truncates the file, thus ensuring the 
resulting file will have the "right" size. Without truncation, the updated file 
might be as big as the original, even if information were deleted. 

SEE ALSO 

cof2elf (1), creat(2), lseek(2), open(2), elf(3E), elf_cntl(3E), elf_end(3E), 
elf_getarhdr(3E), elf_getbase(3E), elf_getdata(3E), elf_getehdr(3E), 
elf_getphdr(3E), elf jcretscn(3E), elf Jcind(3E), elf_next(3E), elf_rand(3E), 
elf_rawf ile(3E), elfjiipdate(3E), elf_version(3E), ar(4) 

NOTES 

COFF is an object file format that preceded ELF. When a program calls 
elf_begin on a COFF file, the library translates COFF structures to their ELF 
equivalents, allowing programs to read (but not to write) a COFF file as if it were 
ELF. This conversion happens only to the memory image and not to the file 
itself. After the initial elf_begin, file offsets and addresses in the ELF header, 
the program headers, and the section headers retain the original COFF values [see 
elfjgetehdr, elfjgetphdr, and elfjgetshdr]. A program may call 
elf jupdate to adjust these values (without writing the file), and the library will 
then present a consistent, ELF view of the file. Data obtained through 
elfjgetdat:a are translated (the COFF symbol table is presented as ELF, etc.). 
Data viewed through elf_j:awdat:a imdergo no conversion, allowing the program 
to view the bytes from the file itself. 

Some COFF debugging information is not translated, though this does not affect 
the semantics of a running program. 

Although the ELF library supports COFF, programmers are strongly encouraged 
to recompile their programs, obtaining ELF object files. 
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NAME 

elf_cntl - control a file descriptor 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 
int elf__cntl (Elf *elf, Elf_Cml cmd) ; 
DESCRIPTION 

elf_ca:itl instructs the library to modify its behavior with respect to an ELF 
descriptor, elf. As elfJ:>egin(3E) describes, an ELF descriptor can have multiple 
activations, and multiple ELF descriptors may share a single file descriptor. Gen- 
erally, elf__cntl commands apply to all activations of elf. Moreover, if the ELF 
descriptor is associated with an archive file, descriptors for members within the 
archive will also be affected as described below. Unless stated otherwise, opera- 
tions on archive members do not affect the descriptor for the containing archive. 

The cmd argument tells what actions to take and may have the following values. 

ELF_C_FDDONE 

This value tells the library not to use the file descriptor associated with 
elf. A program should use this command when it has requested all 
the information it cares to use and wishes to avoid the overhead of 
reading the rest of the file. The memory for all completed operations 
remains valid, but later file operations, such as the initial elf__getdata 
for a section, will fail if the data are not in memory already. 

ELF^CJDREAD 

This command is similar to ELFjC_FDDONE, except it forces the library 
to read the rest of the file. A program should use this command when 
it must close the file descriptor but has not yet read everything it 
needs from the file. After elf_cntl completes the ELFjC_FDREAD 
command, future operations, such as elfjgetdata, will use the 
memory version of the file without needing to use the file descriptor. 

If elf_cntl succeeds, it returns zero. Otherwise elf was null or an error 
occurred, and the function returns -1. 

SEE ALSO 

elf (3E), elf_begin(3E), elf_getdata(3E), elf_rawfile(3E). 

NOTE 

If the program wishes to use the "raw" operations [see elf__rawdata, which 
elf__getdata(3E) describes, and elf_rawf ile(3E)] after disabling the file descrip- 
tor with ELF_C_FDDONE or ELF_C__FDREAD, it must execute the raw operations 
explicitly beforehand. Otherwise, the raw file operations will fail. Calling 
elf_rawfile makes the entire image available, thus supporting subsequent 
elf rawdata calls. 
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NAME 

elf_end - finish using an object file 

SYNOPSIS 

cc Iflag ..,] file --lelf [library . . .] 

♦include <libelf .h> 
int elf_end(Elf *elf ) ; 
DESCRIPTION 

A program uses elf_end to terminate an ELF descriptor, elf, and to deallocate 
data associated with the descriptor. Until the program terminates a descriptor, 
the data remain allocated, elf should be a value previously returned by 
elf^begin; a null pointer is allowed as an argument, to simplify error handling. 
If the program wishes to write data associated with the ELF descriptor to the file, 
it must use elf jupdate before calling elf jend. 

As elf_begin(3E) explains, a descriptor can have more than one activation. Cal- 
ling elf jend removes one activation and returns the remaining activation count. 
The library does not terminate the descriptor until the activation count reaches 
zero. Consequently, a zero return value indicates the ELF descriptor is no longer 
valid. 

SEE ALSO 

elf (3E), elf J>egin(3E), elf japdate(3E). 
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NAME 

elf jerrmsg, elf jerrno - error handling 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

tinclude <libelf .h> 

const char *elf_jernnsg(int err); 
int elf_ermo (void) ; 

DESCRIPTION 

If an ELF library function fails, a program may call elfjerrno to retrieve the 
library's internal error number. As a side effect, this function resets the internal 
error number to zero, which indicates no error. 

elf^ernnsg takes an error number, err, and returns a null-terminated error mes- 
sage (with no trailing new-line) that describes the problem. A zero err retrieves a 
message for the most recent error. If no error has occurred, the return value is a 
null pointer (not a pointer to the null string). Using err of -1 also retrieves the 
most recent error, except it guarantees a non-null return value, even when no 
error has occurred. If no message is available for the given number, elf^errmsg 
returns a pointer to an appropriate message. This function does not have the side 
effect of clearing the internal error nimiber. 

EXAMPLE 

The following fragment clears the internal error number and checks it later for 
errors. Unless an error occurs after the first call to elf jerrno, the next call will 
return zero. 

(void) elf jerrno ( ) ; 
while (more_tojdo) 
{ 

/* processing ... */ 

if ((err = elfjerrnoO) != 0) 

{ 

xnsg = elfjerrmsg (err) ; 
/* print msg */ 

} 

} 

SEE ALSO 

elf (3E), elf_version(3E). 
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NAME 

elf__f ill - set fill byte 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 
void elf_fill(int fill); 
DESCRIPTION 

Alignment constraints for ELF files sometimes require the presence of "holes." 
For example, if the data for one section are required to begin on an eight-byte 
boundary, but the preceding section is too "short," the library must fill the inter- 
vening bytes. These bytes are set to the fill character. The library uses zero bytes 
unless the application supplies a value. See elfjgetdata(3E) for more informa- 
tion about these holes. 

SEE ALSO 

elfOE), elf_getdata(3E), elf_f lag(3E), elf japdate(3E). 

NOTE 

An application can assume control of the object file organization by setting the 
ELFJgVLAYOUT bit [see elf_f lag(3E)]. When this is done, the library does not fill 
holes. 
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NAME 

elf_flagdata, elf_flagehdr, elf_flagelf, elf_flagphdr, elf__flagscn, 
elf_f lagshdr - manipulate flags 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 

unsigned elf_f lagdata (Elf_Data *datar ElfjCmd and, unsigned flags); 
unsigned elf_f lagehdr (Elf *elf , ElfjCmd and, unsigned flags) ; 
unsigned elf_f lagelf (Elf *elf, ElfjCmd and, unsigned flags); 
unsigned elf__f lagphdr (Elf *elf , ElfjCmd and, unsigned flags) ; 
unsigned elf_f lagsoi (Elf__Scn *scn, ElfjCmd and, unsigned flags); 
unsigned elf__f lagshdr (Elf_Saci *scn, ElfjQnnd and, unsigned flags); 
DESCRIPTION 

These functions manipulate the flags associated with various structures of an ELF 
file. Given an ELF descriptor (elfX a data descriptor (data), or a section descriptor 
(sen), the functions may set or clear the associated status bits, returning the 
updated bits. A null descriptor is allowed, to simplify error handling; all func- 
tions return zero for this degenerate case. 

and may have the following values. 

ELFjCjCLR The functions clear the bits that are asserted in flags. Only 

the non-zero bits in flags are cleared; zero bits do not change 
the status of the descriptor. 

ELFjC_SET The fimctions set the bits that are asserted in flags. Only the 

non-zero bits in flags are set; zero bits do not change the 
status of the descriptor. 

Descriptions of the defined flags bits appear below. 

ELF_F_piRTY When the program intends to write an ELF file, this flag 
asserts the associated information needs to be written to the 
file. Thus, for example, a program that wished to update the 
ELF header of an existing file would call elf__f lagehdr with 
this bit set in flags and and equal to ELF_C__SET. A later call 
to elf jupdate would write the marked header to the file. 

ELF_EJLAYOUT Normally, the library decides how to arrange an output file. 

That is, it automatically decides where to place sections, how 
to align them in the file, etc. If this bit is set for an ELF 
descriptor, the program assumes responsibility for determin- 
ing all file positions. This bit is meaningful only for 
elf_f lagelf and applies to the entire file associated with the 
descriptor. 



10/89 



Page 1 



elf_flag(3E) 



elfJlag(3E) 



When a flag bit is set for an item, it affects all the subitems as well. Thus, for 
example, if the program sets the ELFJFJDIRTY bit with elf_f lagelf, the entire 
logical file is "dirty/' 

EXAMPLE 

The following fragment shows how one might mark the ELF header to be written 
to the output file. 

ehdr = elf32__getehdr (elf ) ; 
/* dirty ehdr . . . */ 

elf_flagehdr(elf, ELF_C_SET, ELFJFJDIRTY) ; 

SEE ALSO 

elfOE), elf_end(3E), elf_getdata(3E), elf_getehdr(3E), elf jupdate(3E). 
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NAME 

elf_f size: elf 32_f size - return the size of an object file type 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

sizejt elf 32_f size (Elf JType type, size__t count, unsigned ver) ; 
DESCRIPTION 

elf 32_f size gives the size in bytes of the 32-bit file representation of count data 
objects with the given type. The library uses version ver to calculate the size [see 
elf(3E) and elf_version(3E)]. 

Constant values are available for the sizes of fundamental types. 



ElfJType File Size Memory Size 



ELF 


T 


ADDR 


ELF32 


FSZ_ 


ADDR 


sizeof (Elf 32_Addr) 


ELF 




BYTE 


1 






sizeof (unsigned char) 


ELF 


Y 


"half 


ELF32 


FSZ 


HALF 


sizeof (Elf 32 Half) 


ELT^ 


Y 


"off 


ELF32' 


'fsz" 


"off 


sizeof (Elf 32_Off) 


elf" 


Y 


"sword 


ELF32" 


"fsz" 


"sword 


sizeof (Elf 32 Sword) 


elf' 


Y 


WORD 


ELF32' 


"fsz' 


"word 


sizeof (Elf 32 Wbrd) 

















elf32_fsize returns zero if the value of type or ver is unknown. See 
elf__xlate(3E) for a list of the type values. 

SEE ALSO 

elf (3E), elf_yersion(3E), elf_xlate(3E). 
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NAME 

elf_getarhdr - retrieve archive member header 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 
Elf_Arhdr *elf_getarhdr (Elf ♦elf ) ; 
DESCRIPTION 

elfjgetarhdr returns a pointer to an archive member header, if one is available 
for the ELF descriptor elf. Otherwise, no archive member header exists, an error 
occurred, or elf was null; elf_getarhdr then returns a null value. The header 
includes the following members. 

char 
time__t 
long 
long 

unsigned long 
off_t 
char 

An archive member name, available through ar_name, is a null-terminated string, 
with the ar format control characters removed. The arjrawname member holds a 
null-terminated string that represents the original name bytes in the file, including 
the terminating slash and trailing blanks as specified in the archive format. 

In addition to "regular" archive members, the archive format defines some spe- 
cial members. All special member names begin with a slash (/), distinguishing 
them from regular members (whose names may not contain a slash). These spe- 
cial members have the names (arjname) defined below. 

/ This is the archive symbol table. If present, it will be the first archive 

member. A program may access the archive symbol table through 
elf_getarsyxn. The information in the symbol table is useful for ran- 
dom archive processing [see elf_rand(3E)]. 

// This member, if present, holds a string table for long archive member 
names. An archive member's header contains a 16-byte area for the 
name, which may be exceeded in some file systems. The library 
automatically retrieves long member names from the string table, setting 
ar_name to the appropriate value. 

Under some error conditions, a member's name might not be available. Although 
this causes the library to set arjname to a null pointer, the cu:_rawname member 
will be set as usual. 

SEE ALSO 

elf (3E), elf_begin(3E), elf_getarsyin(3E), elf_rand(3E), ar(4). 



♦arjname; 

ar_date; 

arjuid; 

ar_gid; 

ar__roode; 

ar_size; 

*ar rawname; 
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NAME 

elf__getarsym - retrieve archive symbol table 

SYNOPSIS 

cc Iflag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

Elf_Arsym *elf__getarsym(Elf *elf , size_t *ptr) ; 
DESCRIPTION 

elfjgetarsym returns a pointer to the archive symbol table, if one is available 
for the ELF descriptor elf. Otherwise, the archive doesn't have a s)mibol table, an 
error occurred, or elf was null; elf_getarsym then returns a null value. The 
symbol table is an array of structures that include the following members. 

char * as^name ; 

size_t as_off; 
unsigned long as_hash; 

These members have the following semantics. 

as_naine A pointer to a null-terminated symbol name resides here. 

as_of f This value is a byte offset from the beginning of the archive to the 
member's header. The archive member residing at the given offset 
defines the associated symbol. Values in asjof f may be passed as 
arguments to elfjrand to access the desired archive member. 

as_Jiash This is a hash value for the name, as computed by elf__hash. 

If ptr is non-null, the library stores the number of table entries in the location to 
which ptr points. This value is set to zero when the return value is null. The 
table's last entry, which is included in the count, has a null as_naine, a zero value 
for as_of f, and -OUL for asjiash. 

SEE ALSO 

elf (3E), elf_getarhdr(3E), elfJiashOE), elf__rand(3E), ar(4). 
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NAME 

elfjgetbase - get the base offset for an object file 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 
off J: elf_get±>ase (Elf *elf ) ; 
DESCRIPTION 

elf_getbase returns the file offset of the first byte of the file or archive member 
associated with elf, if it is known or obtainable, and -1 otherwise. A null elf is 
allowed, to simplify error handling; the return value in this case is -1. The base 
offset of an archive member is the beginning of the member's information, not the 
beginning of the archive member header. 

SEE ALSO 

elf (3E), elf_begin(3E), ar(4). 
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NAME 

elf_c|etdata, elf_newdata, elf_rawdata - get section data 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

Elf_pata *elf__getdata(Elf_Scn *scn, ElfJ)ata *data) ; 
Elf_Data *elfjfiewdata(Elf_Scn *scn); 
ElfJData *elf_rawdata(Elf_Scn *scn, ElfJ)ata *data) ; 
DESCRIPTION 

These functions access and manipulate the data associated with a section descrip- 
tor, sen. When reading an existing file, a section will have a single data buffer 
associated with it. A program may build a new section in pieces, however, com- 
posing the new data from multiple data buffers. For this reason, "the" data for a 
section should be viewed as a list of buffers, each of which is available through a 
data descriptor. 

elf_jgetdata lets a program step through a section's data list. If the incoming 
data descriptor, data, is null, the function returns the first buffer associated with 
the section. Otherwise, data should be a data descriptor associated with sen, and 
the function gives the program access to the next data element for the section. If 
sen is null or an error occurs, elf jgfetdata returns a null pointer. 

elfjgetdata translates the data from file representations into memory represen- 
tations [see elf_xlate(3E)] and presents objects with memory data types to the 
program, based on the file's class [see elf(3E)]. The working library version [see 
elf_version(3E)l specifies what version of the memory structures the program 
wishes elfjgetdat:a to present. 

elfjnewdata creates a new data descriptor for a section, appending it to any 
data elements already associated with the section. As described below, the new 
data descriptor appears empty, indicating the element holds no data. For con- 
venience, the descriptor's type (d__type below) is set to ELF_T_BYTE, and the ver- 
sion (diversion below) is set to the working version. The program is responsi- 
ble for setting (or changing) the descriptor members as needed. This function 
implicitly sets the ELF_F_piRTY bit for the section's data [see elf__flag(3E)]. If 
sen is null or an error occurs, elf_newdata returns a null pointer. 

elf_rawdata differs from elfjgetdata by returning only iminterpreted bytes, 
regardless of the section type. This function typically should be used only to 
retrieve a section image from a file being read, and then only when a program 
must avoid the automatic data translation described below. Moreover, a program 
may not close or disable [see elf_jcntl(3E)] the file descriptor associated with elf 
before the initial raw operation, because elf_j:awdata might read the data from 
the file to ensure it doesn't interfere with elfjgetdata. See elf_rawf ile(3E) 
for a related facility that applies to the entire file. When elfjgetdata provides 
the right translation, its use is recommended over elf_rawdata. If sen is null or 
an error occurs, elf_rawdat:a returns a null pointer. 
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The ElfJData structure includes the following members. 

void *d_buf; 

ElfJType d_type; 

size_t d_size; 

off_t djoff; 

size_t d_align; 

unsigned diversion; 

These members are available for direct manipulation by the program. Descrip- 
tions appear below. 

djDuf A pointer to the data buffer resides here. A data element with no 

data has a null pointer. 

d_type This member's value specifies the type of the data to which djDuf 

points. A section's type determines how to interpret the section 
contents, as summarized below. 

d_size This member holds the total size, in bytes, of the memory occu- 

pied by the data. This may differ from the size as represented in 
the file. The size will be zero if no data exist. [See the discussion 
of SHT_NOBITS below for more information.] 

d_off This member gives the offset, within the section, at which the 

buffer resides. This offset is relative to the file's section, not the 
memory object's. 

d_align This member holds the buffer's required alignment, from the 
beginning of the section. That is, d_of f will be a multiple of this 
member's value. For example, if this member's value is four, the 
beginning of the buffer will be four-byte aligned within the sec- 
tion. Moreover, the entire section will be aligned to the maximimi 
of its constituents, thus ensuring appropriate alignment for a 
buffer within the section and within the file. 

diversion This member holds the version number of the objects in the 
buffer. When the library originally read the data from the object 
file, it used the working version to control the translation to 
memory objects. 

DATA ALIGNMENT 

As mentioned above, data buffers within a section have explicit alignment con- 
straints. Consequently, adjacent buffers sometimes will not abut, causing "holes" 
within a section. Programs that create output files have two ways of dealing with 
these holes. 

First, the program can use elf_f ill to tell the library how to set the intervening 
bytes. When the library must generate gaps in the file, it uses the fill byte to ini- 
tialize the data there. The library's initial fill value is zero, and elf_f ill lets the 
application change that. 

Second, the application can generate its own data buffers to occupy the gaps, 
filling the gaps with values appropriate for the section being created. A program 
might even use different fill values for different sections. For example, it could 
set text sections' bytes to no-operation instructions, while filling data section holes 
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with zero. Using this technique, the library finds no holes to fill, because the 
application eliminated them. 

SECTION AND MEMORY TYPES 

el£_getdata interprets sections' data according to the section type, as noted in 
the section header available through elfjgetshdr. The following table shows 
the section types and how the library represents them with memory data types 
for the 32-bit file class. Other classes would have similar tables. By implication, 
the memory data types control translation by elf_xlate. 



Section Type Elf JType 32-Bit Type 



SHT DYNAMIC 


ELF 


T 


DYN 


Elf32 Dyn 


SHT DYNSYM 


elf" 


"t" 


"SYM 


Elf32 Sym 


SHTJIASH 


elf' 


"t" 


WORD 


Elf32_Word 


SHT NOBITS 


elf" 


't' 


byte 


unsigned char 


SHT NOTE 


elf' 


Y 


byte 


unsigned char 


SHT NULL 


none 






none 


SHT PROGBITS 


ELF 


T 


byte 


unsigned char 


SHT REL 


elf" 


"t" 


"rel 


Elf32 Rel 


SHT_RELA 


elf" 


"t" 


JCEIA 


Elf32_Rela 


SHT STRTAB 


elf" 


"t" 


BYTE 


unsigned cheu: 


SHT_SYMrAB 


elf" 


"t" 


'SYM 


Elf32_Sym 


other 


elf" 


"t 


BYTE 


unsigned char 



elf_rawdata creates a buffer with type ELFjr__BYTE. 

As mentioned above, the program's working version controls what structures the 
library creates for the application. The library similarly interprets section types 
according to the versions. If a section type "belongs" to a version newer than the 
application's working version, the library does not translate the section data. 
Because the application cannot know the data format in this case, the library 
presents an untranslated buffer of type ELFjr_BYTE, just as it would for an 
unrecognized section type. 

A section with a special type, SHT__NOBITS, occupies no space in an object file, 
even when the section header indicates a non-zero size, elfjgetdata and 
elf_jrawdata "work" on such a section, setting the data structure to have a null 
buffer pointer and the type indicated above. Although no data are present, the 
d_size value is set to the size from the section header. When a program is creat- 
ing a new section of type SHTJNOBITS, it should use elf_newdata to add data 
buffers to the section. These "empt/' data buffers should have the d_size 
members set to the desired size and the djDuf members set to null. 

EXAMPLE 

The following fragment obtains the string table that holds section names (ignor- 
ing error checking). See elf__strptr(3E) for a variation of string table handling. 
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ehdr = elf 32_getehdr (elf ) ; 

sen = elfjgetscn(elf , (sizejt)ehdr->e_shstrndx) ; 

shdr = elf32__getshdr (sen) / 

if (shdr->shj:ype != SHT_STRTAB) 

{ 

/* not a string table */ 

} 

data » 0; 

if ((data « elfjgetdata(scn, data)) ~ 0 || data->djsize ~ 0) 
{ 

/* error or no data */ 

} 

The e__shstrndx member in an ELF header holds the section table index of the 
string table. The program gets a section descriptor for that section, verifies it is a 
string table, and then retrieves the data. When this fragment finishes, data- 
>d_buf points at the first byte of the string table, and data->d__size holds the 
string table's size in bytes. 

SEE ALSO 

elf (3E), elf_entl(3E), elf_f ill(3E), elf_f lag(3E), elf_getehdr(3E), 
elf_getscn(3E), elf__getshdr(3E), elf_rawf ile(3E), elf jversion(3E), 
elf xlate(3E). 
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NAME 

elf_getehdr: elf 32__getehdr, elf 32__newehdr - retrieve class-dependent object 
file header 

SYNOPSIS 

cc [flag ...]file ... -lelf [library . . .] 

♦include <libelf .h> 
Elf32JEhdr *elf 32_getehdr (Elf ♦elf); 
Elf32_Ehdr ♦elf 32_newehdr (Elf ♦elf); 
DESCRIPTION 

For a 32-bit class file, elf 32_getehdr returns a pointer to an ELF header, if one is 
available for the ELF descriptor elf. If no header exists for the descriptor, 
elf32_newehdr allocates a "clean" one, but it otherwise behaves the same as 
elf32_getehdr. It does not allocate a new header if one exists already. If no 
header exists (for elfjgetehdr), one cannot be created (for elf__newehdr), a sys- 
tem error occurs, the file is not a 32-bit class file, or elf is null, both functions 
return a null pointer. 

The header includes the following members. 



elf32_newehdr automatically sets the ELF_FJ)IRTY bit [see elf_flag(3E)]. A 
program may use elf_jgetident to inspect the identification bytes from a file. 

SEE ALSO 

elf(3E), elf J)egin(3E), elf__f lag(3E), elf_getident(3E). 



unsigned char 



evident [EI_NIDENT] ; 
e__type; 
e_machine; 
e version; 



Elf32_Half 

Elf32JIalf 

Elf32JWord 

Elf32__Addr 

Elf32j0ff 

Elf32j0ff 

Elf32_Word 

Elf32_Half 

Elf32JIalf 

Elf32_Half 

Elf32_Half 

Elf32Jialf 

Elf32 Half 



e_jentry; 
e_phoff ; 
e_shoff ; 
e__flags; 
e ehsize; 



ejphentsize; 
e__phnum; 
e_shentsize; 
e_shnum; 
e shstrndx; 
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NAME 

elf_c|eticlent - retrieve file identification data 

SYNOPSIS 

cc [flag .,.]file ... -lelf [library . . .] 

♦include <libelf .h> 

char *elf_getident (Elf *elf, size_t *ptr); 
DESCRIPTION 

As elf (3E) explains, ELF provides a framework for various classes of files, where 
basic objects may have 32 bits, 64 bits, etc. To accommodate these differences, 
without forcing the larger sizes on smaller machines, the initial bytes in an ELF 
file hold identification information common to all file classes. Every ELF header's 
evident has EI_NIDENT bytes with the following interpretation. 



e_ident Index 


Value 


Purpose 


EI MkGO 
EI MAGI 
EI MAG2 
EIJ!AG3 


ELFMAGO 
ELFMAGl 
ELFMAG2 
ELFMAG3 


File identification 


EIJCLASS 


ELFCLASSNONE 

ELFCLASS32 

ELFCLASS64 


File class 


EIJ)ATA 


ELFDATANONE 
ELFDATA2LSB 
ELFDATA2MSB 


Data encoding 


EI_VERSION 


EV_CURRENT 


File version 


7-15 


0 


Unused, set to zero 



Other kinds of files [see elf__kind(3E)] also may have identification data, though 
they would not conform to evident. 

elf_getident returns a pointer to the file's "initial bytes." If the library recog- 
nizes the file, a conversion from the file image to the memory image may occur. 
In any case, the identification bytes are guaranteed not to have been modified, 
though the size of the unmodified area depends on the file type. If ptr is non- 
null, the library stores the number of identification bytes in the location to which 
ptr points. If no data are present, elf is null, or an error occurs, the return value is 
a null pointer, with zero optionally stored through ptr. 

SEE ALSO 

elf(3E), elf_begin(3E), elf_getehdr(3E), elf_kind(3E), elf_rawfile(3E). 
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NAME 

elf_getphdr: elf32_getphdr, elf32j:iewphdr - retrieve class-dependent pro- 
gram header table 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 
Elf32_Phdr *elf 32_getphdr (Elf *elf ) ; 
Elf32_Phdr *elf 32_newphdr (Elf *elf, sizejt count); 
DESCRIPTION 

For a 32-bit class £Qe, elf 32_getphdr returns a pointer to the program execution 
header table, if one is available for the ELF descriptor elf. 

elf 32_newphdr allocates a new table with count entries, regardless of whether 
one existed previously, and sets the ELF_F_piRTY bit for the table [see 
elf_flag(3E)]. Specifying a zero count deletes an existing table. Note this 
behavior differs from that of elf32__newehdr [see elf32__getehdr(3E)], allowing 
a program to replace or delete the program header table, changing its size S 
necessary. 

If no program header table exists, the file is not a 32-bit class file, an error occurs, 
or elf is null, both functions return a null pointer. Additionally, elf 32_jiewphdr 
returns a null pointer if count is zero. 

The table is an array of Elf32jPhdr structures, each of which includes the fol- 
lowing members. 

Elf32JWord P_type; 
Elf32jDff p_offset; 
Elf32_Addr p_vaddr; 
Elf32__Addr pjpaddr; 
Elf32_Word p_filesz; 
Elf32_Word p_memsz; 
Elf32J?ord p_flags; 
Elf32JWord p_align; 

The ELF header's e_phnum member tells how many entries the program header 
table has [see elf jgetehdr(3E)l. A program may inspect this value to determine 
the size of cm existing table; elf32_newphdr automatically sets the member's 
value to count . If the program is building a new file, it is responsible for creating 
the file's ELF header before creating the program header table. 

SEE ALSO 

elf (3E), elf J>egin(3E), elf__flag(3E), elf_getehdr(3E). 
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NAME 

elf_getscn, elf_ndxscn, elf_newscn, elfjiextscn - get section information 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 

Elf_Scn *elfjgetscn(Elf *elf^ sizejt index); 
sizejt elfjidxscn(Elf_Scn *3cn) ; 
Elf_Scn *elf_newscn (Elf *elf ) ; 
Elf_Scn *elf_nextscn (Elf *elf, ElfJScn *scn) ; 
DESCRIPTION 

These ftinctions provide indexed and sequential access to the sections associated 
with the ELF descriptor elf. If the program is building a new file, it is responsible 
for creating the file's ELF header before creating sections; see elf_getehdr(3E). 

elf_getscn returns a section descriptor, given an index into the file's section 
header table. Note the first "real" section has index 1. Although a program can 
get a section descriptor for the section whose index is 0 (SHNJUNDEF, the 
undefined section), the section has no data and the section header is "empty" 
(though present). If the specified section does not exist, an error occurs, or elf is 
null, elfjgetscn returns a null pointer. 

elf_jiewscn creates a new section and appends it to the list for elf. Because the 
SHNJCJNDEF section is required and not "interesting" to applications, the library 
creates it automatically. Thus the first call to elf_newscn for an ELF descriptor 
with no existing sections returns a descriptor for section 1. If an error occurs or 
elf is null, elf jnewscn returns a null pointer. 

After creating a new section descriptor, the program can use elf__getshdr to 
retrieve the newly created, "clean" section header. The new section descriptor 
will have no associated data [see elfjgetdata(3E)]. When creating a new sec- 
tion in this way, the library updates the e_shnum member of the ELF header and 
sets the ELFJF_piRTY bit for the section [see elf_flag(3E)l. If the program is 
building a new file, it is responsible for creating the file's ELF header [see 
elf_getehdr(3E)] before creating new sections. 

elf__nextscn takes an existing section descriptor, sen, and returns a section 
descriptor for the next higher section. One may use a null sen to obtain a section 
descriptor for the section whose index is 1 (skipping the section whose index is 
SHNJDNDEF). If no further sections are present or an error occurs, elf jnextscn 
returns a null pointer. 

elf_ndxscn takes an existing section descriptor, sen, and returns its section table 
index. If sen is null or an error occurs, elf_ndxscn returns SHNJDNDEF. 

EXAMPLE 

An example of sequential access appears below. Each pass through the loop 
processes the next section in the file; the loop terminates when all sections have 
been processed. 
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sen = 0; 

while ((sen = elf_nextscn (elf , sen)) != 0) 
{ 

/* process seetion */ 

} 

SEE ALSO 

elf (3E), elfJ>egin(3E), elf_f lag(3E), elf_getdata(3E), elf_getehdr(3E), 
elf_getshdr(3E). 
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NAME 



elf jgetshdr: elf 32jgetshdlr - retrieve class-dependent section header 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

Elf32_Shdr *elf32_getshdr (Elf_Scn ♦sen) / 
DESCRIPTION 

For a 32-bit class file, elf 32_9etshdr returns a pointer to a section header for the 
section descriptor sen. Otherwise, the file is not a 32-bit class file, sen was null, or 
an error occurred; elf 32 jgetshdr then returns null. 

The header includes the following members. 



If the program is building a new file, it is responsible for creating the file's ELF 
header before creating sections. 

SEE ALSO 

elf (3E), elf_f lag(3E), elf_getscn(3E), elf jstrptr(3E). 



Elf32JWrord 

Elf32_Word 

Elf32JWord 

Elf32_Addr 

Elf32j0ff 

Elf32JWord 

Elf32JWord 

Elf32JWord 

Elf32__Word 

Elf32 Word 



shjnaine; 
sh_type; 
sh__flags; 
sh addr; 



sh offset; 



shjsize; 
sh_link; 
sh info; 



sh_addralign ; 
sh entsize; 
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NAME 

elf_hash - compute hash value 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 

unsigned long elf_hash (const char *naine) ; 
DESCRIPTION 

elf_hash computes a hash value, given a null terminated string, name. The 
returned hash value, h, can be used as a bucket index, typically after computing 
h mod X to ensure appropriate boimds. 

Hash tables may be built on one machine and used on another because elf_hash 
uses unsigned arithmetic to avoid possible differences in various machines' 
signed arithmetic. Although name is shown as char* above, elf__hash treats it as 
unsigned char* to avoid sign extension differences. Using char* eliminates 
type conflicts with expressions such as elf_hash("naine") . 

ELF files' symbol hash tables are computed using this function [see 
elf_getdata(3E) and elf_xlate(3E)]. The hash value returned is guaranteed 
not to be the bit pattern of all ones (-OUL). 

SEE ALSO 

elf (3E), elf_getdata(3E), elf j}clate(3E). 
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NAME 

elf_kind - determine file type 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 
ElfJCind elf_kind(Elf *elf ) ; 
DESCRIPTION 

This function returns a value identifying the kind of file associated with an ELF 
descriptor (elf). Currently defined values appear below. 

ELF_K_AR The file is an archive [see ar(4)]. An ELF descriptor may also be 

associated with an archive member, not the archive itself, and 
then elf_kind identifies the member's type. 

ELF_Kj:OFF The file is a COFF object file. elf_begin(3E) describes the 
library's handling for COFF files. 

ELF_K_ELF The file is an ELF file. The program may use elf__getident to 
determine the class. Other functions, such as elf_getehdr, are 
available to retrieve other file information. 

ELF_K_NONE This indicates a kind of file unknown to the library. 

Other values are reserved, to be assigned as needed to new kinds of files, elf 
should be a value previously returned by elfjbegin. A null pointer is allowed, 
to simplify error handling, and causes elf_kind to return ELF_K_JIONE. 

SEE ALSO 

elf (3E), elf jDeginOE), elf__getehdr(3E), elf__getident(3E), ar(4). 
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NAME 

elf_next - sequential archive member access 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 
Elf^Cmd elf__next (Elf *elf ) ; 
DESCRIPTION 

elf_next, elf_ran<t and elfjbegin manipulate simple object files and archives. 
elf is an ELF descriptor previously returned from elfjbegin. 

elfj:iext provides sequential access to the next archive member. That is, having 
an ELF descriptor, elf, associated with an archive member, elfjiext prepares the 
containing archive to access the following member when the program calls 
elfjbegin. After successfully positioning an archive for the next member, 
elf_next returns the value ELFjC_READ. Otherwise, the open file was not an 
archive, elf was null, or an error occurred, and the return value is ELF_C__NULL. 
In either case, the return value may be passed as an argument to elf_begin, 
specifying the appropriate action. 

SEE ALSO 

elf (3E), elf_begin(3E), elf_getarsym(3E), elf_rand(3E), ar(4). 
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NAME 

elf_rand - random archive member access 

SYNOPSIS 

cc [flag . . .] file . . . -lelf [library . . .] 

♦include <libelf .h> 

size_t elf_rand(Elf *elf^ size__t offset); 
DESCRIPTION 

elf_rand, elf_next, and elf_begin manipulate simple object files and archives. 
elf is an ELF descriptor previously returned from elf Jbegin. 

elf_rand provides random archive processing, preparing elf to access an arbi- 
trary archive member, elf must be a descriptor for the archive itself, not a 
member within the archive, offset gives the byte offset from the beginning of the 
archive to the archive header of the desired member. See elf_getarsyin(3E) for 
more information about archive member offsets. When elf_rand works, it 
returns offset. Otherwise it returns 0, because an error occurred, elf was null, or 
the file was not an archive (no archive member can have a zero offset). A pro- 
gram may mix random and sequential archive processing. 

EXAMPLE 

An archive starts with a "magic string" that has SARMAG bytes; the initial archive 
member follows immediately. An application could thus provide the following 
function to rewind an archive (the fimction returns ~1 for errors and 0 other- 
wise). 

♦include <ar.h> 
♦include <libelf .h> 

int 

rewindelf (Elf ♦elf) 
{ 

if (elf_rand(elf, (sizejt)SARMAG) SARMAG) 

return 0; 
return -1; 

} 

SEE ALSO 

elf (3E), elf jDeginOE), elf_getarsyin(3E), elfjiext(3E), ar(4). 
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NAME 

elf__rawf ile - retrieve uninterpreted file contents 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

char *elf__rawf ile (Elf *elf, size_t *ptr) ; 
DESCRIPTION 

elf_rawf ile returns a pointer to an uninterpreted byte image of the file. This 
function should be used only to retrieve a file being read. For example, a pro- 
gram might use elf_rawf ile to retrieve the bytes for an archive member. 

A program may not close or disable [see elf jcntl(3E)] the file descriptor associ- 
ated with elf before the initial call to elfjrawf ile, because elf_rawf ile might 
have to read the data from the file if it does not already have the original bytes in 
memory. Generally, this function is more efficient for unknown file types than 
for object files. The library implicitly translates object files in memory, while it 
leaves unknown files immodified. Thus asking for the uninterpreted image of an 
object file may create a duplicate copy in memory. 

elf_rawdata [see elf_getdata(3E)] is a related function, providing access to 
sections within a file. 

If ptr is non-null, the library also stores the file's size, in bytes, in the location to 
which ptr points. If no data are present, elf is null, or an error occurs, the return 
value is a null pointer, with zero optionally stored through ptr, 

SEE ALSO 

elf (3E), elf j3egin(3E), elf_cntl(3E), elf__getdata(3E), elf jgetehdr(3E), 
elf_getident(3E), elf Jcind(3E). 

NOTE 

A program that uses elf__rawfile and that also interprets the same file as an 
object file potentially has two copies of the bytes in memory. If such a program 
requests the raw image first, before it asks for translated information (through 
such functions as elf_getehdr, elf jgetdata, and so on), the library "freezes" 
its original memory copy for the raw image. It then uses this frozen copy as the 
source for creating translated objects, without reading the file again. Conse- 
quently, the application should view the raw file image returned by elf__rawf ile 
as a read-only buffer, unless it wants to alter its own view of data subsequently 
translated. In any case, the application may alter the translated objects without 
changing bytes visible in the raw image. 

Multiple calls to elf_rawfile with the same ELF descriptor return the same 
value; the library does not create duplicate copies of the file. 
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NAME 

elf__strptr - make a string pointer 

SYNOPSIS 

cc Iflag . . .] file . . . -lelf [library . . .] 

tinclude <libelf .h> 

char *elf__strptr (Elf *elf, size_t section, size_t offset); 
DESCRIPTION 

This function converts a string section offset to a string pointer, elf identifies the 
file in which the string section resides, and section gives the section table index for 
the strings. elf_strptr normally returns a pointer to a string, but it returns a 
null pointer when elf is null, section is invalid or is not a section of type 
SHT_STRTAB, the section data cannot be obtained, offset is invalid, or an error 
occurs. 

EXAMPLE 

A prototype for retrieving section names appears below. The file header specifies 
the section name string table in the e_shstrndx member. The following code 
loops through the sections, printing their names. 

if ((ehdr = elf32_getehdr (elf) ) == 0) 
{ 

/* handle the error */ 
return; 

} 

ndx = ehdr->e_shstrndx; 
sen = 0; 

while ((sen = elf_nextscn (elf , sen)) != 0) 
{ 

char *naine = 0; 

if ((shdr = elf32_getshdr(scn) ) != 0) 

name = elf_strptr (elf , ndx, (size__t) shdr->sh_naine) ; 
printf ("'%s'\n", name? name: "(null)"); 

} 

SEE ALSO 

elf (3E), elf_getdata(3E), elf_getshdr(3E), elf_xlate(3E). 

NOTE 

A program may call elf_getdata to retrieve an entire string table section. For 
some applications, that would be both more efficient and more convenient than 
using elf_strptr. 



10/89 



Page 1 



elf update (3E) 



elf_update(3E) 



NAME 

elf jiqpdate - update an ELF descriptor 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 

of f_t elf_j:5>date (Elf *elf , Elf__Cnid and) ; 
DESCRIPTION 

elf juqpdate causes the library to examine the information associated with an ELF 
descriptor, elf, and to recalctdate the structural data needed to generate the file's 
image. 

and may have the following values. 

ELFjC_NULL This value tells elfjapdate to recalculate various values, 
updating only the ELF descriptor's memory structures. Any 
modified structures are flagged with the ELF_FJDIRTY bit. A 
program thus can update the structural information and then 
reexamine them without changing the file associated with the 
ELF descriptor. Because this does not change the file, the ELF 
descriptor may allow reading, writing, or both reading and 
writing [see elf_begin(3E)l. 

ELF_C_WRITE If and has this value, elf_update duplicates its ELFjC__NULL 
actions and also writes any "dirty" information associated with 
the ELF descriptor to the file. That is, when a program has used 
elf__getdata or the elf_flag facilities to supply new (or 
update existing) information for an ELF descriptor, those data 
will be examined, coordinated, translated if necessary [see 
elf_xlate(3E)], and written to the file. When portions of the 
file are written, any ELF_F__DIRTY bits are reset, indicating those 
items no longer need to be written to the file [see 
elf_flag(3E)]. The sections' data are written in the order of 
their section header entries, and the section header table is writ- 
ten to the end of the file. 

When the ELF descriptor was created with elf_begin, it must 
have allowed writing the file. That is, the elf_begin command 
must have been either ELF_CJE<DWR or ELFjCJWRITE. 

If elf ji^xiate succeeds, it returns the total size of the file image (not the memory 
image), in bytes. Otherwise an error occurred, and the function returns -1. 

When updating the internal structures, elf_update sets some members itself. 
Members listed below are the application's responsibility and retain the values 
given by the program. 
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Member 


Notes 


evident [EI J)ATA] 


Library controls other evident values 


e_type 




ejnnachine 




e version 




e_entry 




ejphoff 


Only when ELF__F__LAYOUT asserted 


e_shoff 


Only when ELF_FJLAYOUT asserted 


e_flags 




e_shstrndx 









Program Header 



Member 


Notes 


p_type 


The application controls all 


p_joffset 


program header entries 


p_yaddr 




p__paddr 




p__filesz 




p__ineinsz 




p_flags 




p_jalign 





Member 



Notes 



Section Header 



sh_naine 

sh_type 

sh_flags 

sh_jaddr 

sh_offset 

sh_size 

sh__link 

sh_info 

sh_addralign 

sh entsize 



Only when ELF^F^LAYOUT asserted 
Only when ELF_FJLAYOUT asserted 



Only when EM* J^^LAYOUT asserted 
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Member 



Notes 



Data Descriptor 



d_buf 
d_J:ype 
d__size 
d_off 
d_align 



Only when ELF_F_IAYOUT asserted 



d version 



Note the program is responsible for two particularly important members (among 
others) in the ELF header. The e_version member controls the version of data 
structures written to the file. If the version is EVJNONE, the library uses its own 
internal version. The evident [EI_DATA] entry controls the data encoding used 
in the file. As a special case, the value may be ELFDATANONE to request the native 
data encoding for the host machine. An error occurs in this case if the native 
encoding doesn't match a file encoding known by the library. 

Further note that the program is responsible for the shjentsize section header 
member. Although the library sets it for sections with known types, it cannot 
reliably know the correct value for all sections. Consequently, the library relies 
on the program to provide the values for unknown section type. If the entry size 
is unknown or not applicable, the value should be set to zero. 

When deciding how to build the output file, elf__update obeys the alignments of 
individual data buffers to create output sections. A section's most strictly aligned 
data buffer controls the section's alignment. The library also inserts padding 
between buffers, as necessary, to ensure the proper alignment of each buffer. 



elf (3E), elf_begin(3E), elf_f lag(3E), elf__fsize(3E), elf_getdata(3E), 
elf_getehdr(3E), elf_getshdr(3E), elf jx:late(3E). 



As mentioned above, the ELFjCJWRITE command translates data as necessary, 
before writing them to the file. This translation is not always transparent to the 
application program. If a program has obtained pointers to data associated with 
a file [for example, see elf_getehdr(3E) and elf_getdata(3E)], the program 
should reestablish the pointers after calling elfjupdate. 

As elf j3egin(3E) describes, a program may "update" a COFF file to make the 
image consistent for ELF . The ELFjC_NULL command updates only the memory 
image; one can use the ELFjCJWRITE command to modify the file as well. Abso- 
lute executable files (a. out files) require special alignment, which cannot nor- 
mally be preserved between COFF and ELF . Consequently, one may not update 
an executable COFF file with the ELFJC_WRITE command (though ELFjCJNULL is 
allowed). 



SEE ALSO 



NOTE 



10/89 



Page 3 



elf_version(3E) 



elf version (3E) 



NAME 

elf_version - coordinate ELF library and application versions 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <libelf .h> 
unsigned elf_version (unsigned ver) ; 
DESCRIPTION 

As elf (3E) explains, the program, the library, and an object file have independent 
notions of the "latest" ELF version. elf__version lets a program determine the 
ELF library's internal version. It further lets the program specify what memory 
types it uses by giving its own working version, ver, to the library. Every program 
that uses the ELF library must coordinate versions as described below. 

The header file <libelf .h> supplies the version to the program with the macro 
EV_CURRENT. If the library's internal version (the highest version known to the 
library) is lower than that known by the program itself, the library may lack 
semantic knowledge assumed by the program. Accordingly, elf__version will 
not accept a working version unknown to the library. 

Passing ver equal to EVJJONE causes elf_version to return the library's internal 
version, without altering the working version. If ver is a version known to the 
library, elf__version returns the previous (or initial) working version number. 
CHherwise, the working version remains unchanged and elf_yersion returns 
EV_NONE. 

EXAMPLE 

The following excerpt from an application program protects itself from using an 
older library. 

if (elf_version(EV_CURRENT) == EVNONE) 
{ 

/* library out of date */ 
/* recover from error */ 

} 

NOTES 

The working version should be the same for all operations on a particular elf 
descriptor. Changing the version between operations on a descriptor will prob- 
ably not give the expected results. 

SEE ALSO 

elf (3E), elf J>egin(3E), elf jKlate(3E). 
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NAME 

elf jxlate: elf32__xlatetof, elf32_xlatetQm - class-dependent data transla- 
tion 

SYNOPSIS 

cc [flag . . .1 file . . . -lelf llibrary . . .] 

♦include <libelf .h> 

ElfJ)ata *elf32_xlatet^of (ElfJ)ata *dst, const ElfJ)ata ♦src, 
unsigned encode); 

Elf_pata *elf32_xlatetcm(ElfJ)ata *dst, const ElfJ)ata *src, 
unsigned encode); 

DESCRIPTION 

elf32_j}clatetom translates various data structures from their 32-bit class file 
representations to their memory representations; elf 32_xlatetof provides the 
inverse. This conversion is particularly important for cross development environ- 
ments, src is a pointer to the source buffer that holds the original data; dst is a 
pointer to a destination buffer that will hold the translated copy, encode gives the 
byte encoding in which the file objects are (to be) represented and must have one 
of the encoding values defined for the ELF header's e_ident [EI_J>ATA] entry [see 
elf_getident(3E)]. If the data can be translated, the functions return dst. Oth- 
erwise, they return null because an error occurred, such as incompatible types, 
destination buffer overflow, etc. 

elf_getdata(3E) describes the ElfJData descriptor, which the translation rou- 
tines use as follows. 

d_buf Both the source and destination must have valid buffer pointers. 

djtype This member's value specifies the type of the data to which d_buf 

points and the type of data to be created in the destination. The 
program supplies a d^ype value in the source; the library sets 
the destination's d_type to the same value. These values are 
summarized below. 

d_jsize This member holds the total size, in bytes, of the memory occu- 

pied by the source data and the size allocated for the destination 
data. If the destination buffer is not large enough, the routines do 
not change its original contents. The translation routines reset the 
destination's d^size member to the actual size required, after the 
translation occurs. The source and destination sizes may differ. 

diversion This member holds version number of the objects (desired) in the 
buffer. The source and destination versions are independent. 

Translation routines allow the source and destination buffers to coincide. That is, 
dst->d_buf may equal src->djbuf . Other cases where the source and destina- 
tion buffers overlap give undefined behavior. 
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ElfJType 32-Bit Memory Type 



ELF 


T 


ADDR 


elf" 


"t 


BYTE 


elf" 


Y 


"dyn 


elf" 


"t 


"ehdr 


elf" 


"t" 


"half 


elt] 


Y 


"off 


elf" 


't 


'PHDR 


elf" 


"t 


'rel 


elf" 


"t 


"rela 


elf" 


Y 


"SHDR 


elf" 


Y 


'sword 


elf" 


Y 


"SYM 


elf" 


"t" 


"word 



Elf32_Addr 

unsigned char 

Elf32j)yn 

Elf32_Ehdr 

Elf32_Half 

Elf32jDff 

Elf32_Phdr 

Elf32_Rel 

Elf32_Rela 

Elf32_Shdr 

Elf32_Sword 

Elf32_Sym 

Elf32 Wbrd 



'Translating" buffers of type ELFjr__BYTE does not change the byte order. 
SEE ALSO 

elf(3E), elf__f size(3E), elf_getdata(3E), elf__getident(3E). 
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NAME 

nlist - get entries from name list 

SYNOPSIS 

cc [flag ...] file ... -lelf [library . . .] 

♦include <nlist.h> 

int nlist (const char * filename, struct nlist ♦nl) ; 
DESCRIPTION 

nlist examines the name list in the executable file whose name is pointed to by 
filename, and selectively extracts a list of values and puts them in the array of 
nlist structures pointed to by nl. The name list nl consists of an array of struc- 
tures containing names of variables, types, and values. The list is terminated 
with a null name, that is, a null string is in the name position of the structure. 
Each variable name is looked up in the name list of the file. If the name is found, 
the type, value, storage class, and section number of the name are inserted in the 
other fields. The type field may be set to 0 if the file was not compiled with the 
-g option to cc(l). nlist will always return the information for an external sym- 
bol of a given name if the name exists in the file. If an external symbol does not 
exist, and there is more than one symbol with the specified name in the file (such 
as static symbols defined in separate files), the values returned will be for the last 
occurrence of that name in the file. If the name is not found, all fields in the 
structure except n_name are set to 0. 

This function is useful for examining the system name list kept in the file /unix. 
In this way programs can obtain system addresses that are up to date. 

SEE ALSO 

a . out(4) 

DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it does not contain a 
valid name list. 

nlist returns 0 on success, -1 on error. 
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NAME 

basename - return the last element of a path name 

SYNOPSIS 

cc [flag . . .] file . . . -Igen [library . . .] 

♦include <libgen.h> 
char ^basename (char *path) ; 
DESCRIPTION 

Given a pointer to a null-terminated character string that contains a path name, 
basename returns a pointer to the last element of path. Trailing characters 
are deleted. 

If path or *path is zero, pointer to a static constant is returned. 
EXAMPLES 

Input string Output pointer 
/usr/lib lib 
/usr/ usr 
/ / 

SEE ALSO 

dirnaroeOG). 

basename(l) in the User's Reference Manual. 
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NAME 

bgets - read stream up to next delimiter 

SYNOPSIS 

cc [flag ...] file ... -Igen [library . . .] 

linclude <libgen.h> 

char *bgets (char *buffer, size_t *co\int, FILE * stream, 
const char *breakstring) ; 

DESCRIPTION 

bgets reads characters from stream into buffer until either count is exhausted or 
one of the characters in breakstring is encountered in the stream. The read data is 
terminated with a null byte C\0') and a pointer to the trailing null is returned. If 
a breakstring character is encountered, the last non-null is the delimiter character 
that terminated the scan. 

Note that, except for the fact that the returned value points to the end of the read 
string rather than to the beginning, the call 

bgets (buffer, sizeof buffer, stream, "\n") ; 
is identical to 

fgets (buffer, sizeof buffer, stream) ; 

There is always enough room reserved in the buffer for the trailing null. 

If breakstring is a null pointer, the value of breakstring from the previous call is 
used. If breakstring is null at the first call, no characters will be used to delimit 
the string. 

EXAMPLES 

♦include <libgen . h> 

char buffer [8] ; 

/* read in first user name from /etc/passwd */ 
fjp = f open ( "/etc/passwd", "r") ; 
bgets (buff er, 8, fp, ":"); 

DIAGNOSTICS 

NULL is returned on error or end-of-file. Reporting the condition is delayed to the 
next call if any characters were read but not yet returned. 

SEE ALSO 

gets(3S). 
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NAME 

buf split - split buffer into fields 

SYNOPSIS 

cc [flag . . .] file . . . -Igen [library . . .] 

# include <libgen.h> 

sizejt buf split (char *buf^ size_t char **a); 
DESCRIPTION 

buf split examines the buffer, buf, and assigns values to the pointer array, a, so 
that the pointers point to the first n fields in buf that are delimited by tabs or 
new-lines. 

To change the characters used to separate fields, call buf split with buf pointing 
to the string of characters, and n and a set to zero. For example, to use ' : ' . ', 
and ' / as separators along with tab and new-line: 

buf split (":.At\n", 0, (char**)0 ); 

RETURN VALUE 

The number of fields assigned in the array a. If buf is zero, the return value is 
zero and the array is unchanged. Otherwise the value is at least one. The 
remainder of the elements in the array are assigned the address of the null byte at 
the end of the buffer. 

EXAMPLES 

/* 

* set a[0] = "This", a[l] = "is", a[2] = "a", 

* a [3] = "test" 
*/ 

bufsplit("This\tis\ta\ttest\n", 4, a) ; 

NOTES 

buf split changes the delimiters to null bytes in buf. 
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NAME 

copylist - copy a file into memory 

SYNOPSIS 

cc Iflag . . .] file . . . -Igen [library . . .] 

♦include <libgen.h> 

char *copylist (const char ♦filenm, off_t *szptr) / 
DESCRIPTION 

copylist copies a list of items from a file into freshly allocated memory, replac- 
ing new-lines with null characters. It expects two arguments: a pointer filenm to 
the name of the file to be copied, and a pointer szptr to a variable where the size 
of the file will be stored. 

Upon success, cc^ylist returns a pointer to the memory allocated. Otherwise it 
returns NULL if it has trouble finding the file, calling malloc, or opening the file. 

EXAMPLES 

/* read "file" into buf */ 
off_t size; 
char *buf ; 

buf = copylist ("file", fisizey; 
for (i = 0; i < size; i++) 
if(buf [il) 

putchar (buf [i] ) ; 

else 

putchar (' \n' ) ; 

SEE ALSO 

raallocOC). 
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NAME 

dirname - report the parent directory name of a file path name 

SYNOPSIS 

cc [flag ...] file ... -Igen [library . . .] 

♦include <libgen.h> 
char "'dirname (char *path) ; 
DESCRIPTION 

Given a pointer to a null-terminated character string that contains a file system 
path name, dirname returns a pointer to a static constant string that is the parent 
directory of that file. In doing this, it sometimes places a null byte in the path 
name after the next to last element, so the content of path must be disposable. 
Trailing characters in the path are not counted as part of the path. 

If path or *path is zero, a pointer to a static constant is returned. 

dirname and basename together yield a complete path name, dirname (path) is 
the directory where basename (path) is found. 

EXAMPLES 

A simple file name and the strings and all have as their return 

value. 

Input string Output pointer 
/usr/ lib /usr 
/usr/ / 
usr 

/ / 



The following code reads a path name, changes directory to the appropriate 
directory [see chdir(2)], and opens the file. 

char path [100], *pathcopy; 
int fd; 
gets (path) ; 

pathcopy = strdup (path) ; 

chdir (dirname (pathcopy) ) ; 

£d = open (basename (path) , 0_RDONLY) ; 

SEE ALSO 

chdir(2), basename(3G). 

basename(l) in the User's Reference Manual. 
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NAME 

gmatch - shell global pattern matching 

SYNOPSIS 

cc [flag ...] file ... -Igen [library . . .] 

♦include <libgen.h> 

int gmatch (const char ♦str, const char ^pattern) ; 
DESCRIPTION 

gmatch checks whether the null-terminated string sir matches the null-terminated 
pattern string pattern. See the sh(l) section "Rle Name Generation" for a discus- 
sion of pattern matching, gmatch returns non-zero if the pattern matches the 
string, zero if the pattern doesn't. A backslash ('\') is used as an escape character 
in pattern strings. 

EXAMPLE 

char *s; 

gmatch (s, "*[a\-]" > 
gmatch returns non-zero (true) for all strings with 'a' or as their last character. 

SEE ALSO 

sh(l) in the User's Reference Manual 
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NAME 

isencrypt ~ determine whether a character buffer is encrypted 

SYNOPSIS 

cc [flag ...] file ... -Igen [libraiy . . .] 

♦include <libgen.h> 

int isencrypt (const char *fbuf , size_t ninbuf) / 
DESCRIPTION 

isencrypt uses heuristics to determine whether a buffer of characters is 
encrypted. It requires two arguments: a pointer to an array of characters and the 
number of characters in the buffer. 

isencrypt assumes that the file is not encrypted if all the characters in the first 
block are ASCII characters. If there are non-ASCII characters in the first ninbuf 
characters, isencrypt assumes that the buffer is encrypted if the setlocale 
LC_CTYPE category is set to C or ascii. 

If the LCjCTYPE category is set to a value other than C or ascii, then isencrypt 
uses a combination of heuristics to determine if the buffer is encrypted. If ninbuf 
has at least 64 characters, a chi-square test is used to determine if the bytes in the 
buffer have a tmiform distribution; and isencrypt assimies the buffer is 
encrypted if it does. If the buffer has less than 64 characters, a check is made for 
null characters and a terminating new-line to determine whether the buffer is 
encrypted. 

DIAGNOSTICS 

If the buffer is encrypted, 1 is returned; otherwise zero is returned. 

SEE ALSO 

setlocaleOC). 
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NAME 

mkdirp, rmdirp - create, remove directories in a path 

SYNOPSIS 

cc [flag . . .] file . . . -Igen [library . . .] 

♦include <libgen.h> 

int xckdirp (const char *path, modejt mode) ; 
int rmdirp (char *d, char *dl) ; 
DESCRIPTION 

xrikdirp creates all the missing directories in the given path with the given mode. 
[See chinDd(2) for the values of mode.] 

rmdirp removes directories in path d. This removal starts at the end of the path 
and moves back toward the root as far as possible. If an error occurs, the 
remaining path is stored in dl. rmdirp returns a 0 only if it is able to remove 
every directory in the path. 

EXAMPLES 

/♦ create scratch directories */ 

if (mkdirp ("/tmp/subl/sub2/sub3", 0755) == -1) { 

fprintf (stderr, "cannot create directory")/ 

exit(l); 

} 

chdir ("/tmp/subl/sub2/sub3") ; 



/* cleanup */ 

chdir("/trap") ; 

rmdirp ("subl/sub2/sub3") ; 

SEE ALSO 

mkdir(2), rmdir(2). 

DIAGNOSTICS 

If a needed directory cannot be created, mkdirp returns -1 and sets errno to one 
of the mkdir error numbers. If all the directories are created, or existed to begin 
with, it returns zero. 

NOTES 

mkdirp uses malloc to allocate temporary space for the string. 

rmdirp returns -2 if a or is in the path and -3 if an attempt is made 

to remove the current directory. If an error occurs other than one of the above, 
- 1 is returned. 
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NAME 

p2open, p2close - open, close pipes to and from a command 

SYNOPSIS 

cc Iflag ...] file ... -Igen [library . . .] 

♦include <libgen.h> 

int p2open (const char *cmd, FILE *fp[2]); 
int p2close (FILE *fp[2]); 
DESCRIPTION 

p2open forks and execs a shell running the command line pointed to by and. On 
return, fp[0] points to a FILE pointer to write the command's standard input 
and fp[l] points to a FILE pointer to read from the command's standard output. 
In this way the program has control over the input and output of the command. 

The function returns 0 if successful; otherwise it returns -1. 

p2close is used to close the file pointers that p2open opened. It waits for the 
process to terminate and returns the process status. It returns 0 if successful; oth- 
erwise it returns -1. 

EXAMPLES 

linclude <stdio.h> 
♦include <libgen.h> 

main (argc, argv) 
int argc; 
char **argv; 
{ 

FILE *fp[2]; 
pid_t pid; 
char buf [16]; 

pid=p2open ( " /usr/bin/cat " , f p) ; 
if ( pid == 0 ) { 

fprintf (stderr, "p2open failed\n"); 

exit (1) ; 

} 

write (fileno(flp[0]), "This is a test\n", 16); 
if (read(fileno(fp[l]), buf, 16) <=0) 

fprintf (stderr, "p2open failed\n"); 

else 

write (1, buf, 16); 
(void)p2close (fp) ; 

} 

SEE ALSO 

f close(3S), popen(3S), setbuf (3S). 

DIAGNOSTICS 

A common problem is having too few file descriptors. p2close returns -1 if the 
two file pointers are not from the same p2open. 
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NOTES 

Buffered writes on fp[0] can make it appear that the command is not listening. 
Judiciously placed f flush calls or imbuffering fp[01 can be a big help; see 
fcloseOS). 

Many commands use buffered output when connected to a pipe. That, too, can 
make it appear as if things are not working. 

Usage is not the same as for popen, although it is closely related. 
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NAME 

pathfind - search for named file in named directories 

SYNOPSIS 

cc [flag ...] file ... -Igen [library . . .] 

♦include <libgen.h> 

char *pathfind (const char *path^ const char *naine^ const char 
♦mode) ; 

DESCRIPTION 

pathfind searches the directories named in path for the file name. The directories 
named in path are separated by semicolons, mode is a string of option letters 
chosen from the set rwxfbcdpugks: 



Letter Meaning 



r 


readable 


w 


writable 


X 


executable 


f 


normal file 


b 


block special 


c 


character special 


d 


directory 


P 


FIFO (pipe) 


u 


set user ID bit 


g 


set group ID bit 


k 


sticky bit 


s 


size nonzero 



Options read, write, and execute are checked relative to the real (not the effective) 
user ID and group ID of the current process. 

If the file name, with all the characteristics specified by mode, is found in any of 
the directories specified by path, then pathfind returns a pointer to a string con- 
taining the member of path, followed by a slash character (/), followed by name. 

If name begins with a slash, it is treated as an absolute path name, and path is 
ignored. 

An empty path member is treated as the current directory. . / is not prepended 
at the occurrence of the first match; rather, the unadorned name is returned. 

EXAMPLES 

To find the Is command using the PATH environment variable: 
pathfind (getenv ("PATH"), "Is", "rx") 

SEE ALSO 

access(2), inknod(2), stat(2), getenv(3C). 
sh(l), test(l) in the User's Reference Manual. 

DIAGNOSTICS 

If no match is found, pat:hnaroe returns a null pointer, ( (char *) 0) . 



10/89 



Page 1 



pathf ind (3G) pathfind (3G) 

NOTES 

The string pointed to by the returned pointer is stored in a static area that is 
reused on subsequent calls to pathfind. 
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NAME 

regcnp, regex - compile and execute regular expression 

SYNOPSIS 

♦include <libgen.h> 

cc [flag ...] file ... -Igen [library . . .] 

char *regcnp (const char *stringl [, char *string2, . . 
(char *)0); 

char * regex (const char *re^ const char * subject 
[, char *retO, . . .]); 

extern char * ^locl; 

DESCRIPTION 

regcnp compiles a regular expression (consisting of the concatenated arguments) 
and returns a pointer to the compiled form. xnalloc(3C) is used to create space 
for the compiled form. It is the user's responsibility to free unneeded space so 
allocated. A NULL return from regcnp indicates an incorrect argument. 
regcnp(l) has been written to generally preclude the need for this routine at exe- 
cution time. 

regex executes a compiled pattern against the subject string. Additional argu- 
ments are passed to receive values back, regex returns NULL on failure or a 
pointer to the next unmatched character on success. A global character pointer 
^locl points to where the match began, regcirp and regex were mostly bor- 
rowed from the editor, ed(l); however, the syntax and semantics have been 
changed slightly. The following are the valid symbols and associated meanings. 

[ ] * .'^ These symbols retain their meaning in ed(l). 

$ Matches the end of the string; \n matches a newline. 

- Within brackets the minus means through. For example, [a-z] is 

equivalent to [ abed . . . xyz ] . The ~ can appear as itself only if used 
as the first or last character. For example, the character class expres- 
sion [ ] - ] matches the characters ] and 

+ A regular expression followed by + means one or more times. For 

example, [0-9] + is equivalent to [0-9] [0-9] * . 

{m} {m,} {m,M} 

Integer values enclosed in { } indicate the number of times the 
preceding regular expression is to be applied. The value m is the 
minimum number and m is a number, less than 256, which is the max- 
imum. If only m is present (i.e., {m}), it indicates the exact number 
of times the regular expression is to be applied. The value {m,) is 
analogous to {m,infinity} . The plus (+) and star (*) operations are 
equivalent to {1, } and {0, } respectively. 

(...)$« 

The value of the enclosed regular expression is to be returned. The 
value will be stored in the (n+l)th argument following the subject 
argument. At most, ten enclosed regular expressions are allowed, 
regex makes its assignments unconditionally. 
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( ... ) Parentheses are used for grouping. An operator, e.g., *, +, { }, can 
work on a single character or a regular expression enclosed in 
parentheses. For example, (a* (cb+) * ) $0. 

By necessity, all the above defined symbols are special. They must, therefore, be 
escaped with a \ (backslash) to be used as themselves. 

EXAMPLES 

The following example matches a leading newline in the subject string pointed at 
by cursor. 

char *cursor, ♦newcursor, ♦ptr; 

newcursor « regex((ptr = regcnpC'^^Xn", (char *)0)), cursor); 
free (ptr) ; 

The following example matches through the string TestingS and returns the 
address of the character after the last matched character (the "4'0. The string 
Testings is copied to the character array retO. 

char ret0[9]; 

char * newcursor, *naine; 

name = regcnpC ([A-Za-z] [A-za-zO-9] {0,7})$0", (char *)0); 
newcursor = regex(naine, "012Testing345", retO); 

The following example applies a precompiled regular expression in file.i [see 
regcnp(l)] against string, 

♦include "file.i" 

char *string, *newcursor; 

newcursor = regex(naine, string); 

SEE ALSO 

regarpd), mallocOC). 

ed(l) in the User's Reference Manual. 

NOTES 

The user program may run out of memory if regcmp is called iteratively without 
freeing the vectors no longer required. 
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NAME 

regejqpr: coitpile, step, advance - regular expression compile and match rou- 
tines 

SYNOPSIS 

cc [flag ...]file ... -Igen [library . . .] 

♦include <regexpr.h> 

char *corrpile (const char ♦instring, char *expbuf , char *endbuf ) ; 
int step (const char * string, char *expbuf ) ; 
int advance (const char *string, char ♦e^qpbuf ) ; 
extern char *locl, *loc2, *locs; 
extern int nbra, regermo, reglength; 
extern char *braslist[], ♦braelistE]; 
DESCRIPTION 

These routines are used to compile regular expressions and match the compiled 
expressions against lines. The regular expressions compiled are in the form used 
by ed. 

The syntax of the coirpile routine is as follows: 

compile (instring, expbuf, endbuf) 

The parameter instring is a null-terminated string representing the regular expres- 
sion. 

The parameter expbuf points to the place where the compiled regular expression 
is to be placed. If expbuf is NULL, compile uses xnalloc to allocate the space for 
the compiled regular expression. If an error occurs, this space is freed. It is the 
user's responsibility to free unneeded space after the compiled regular expression 
is no longer needed. 

The parameter endbuf is one more than the highest address where the compiled 
regular expression may be placed. This argument is ignored if expbuf is NULL. If 
the compiled expression cannot fit in (endbuf- expbuf) bytes, conpile returns 
NULL and regerrno (see below) is set to 50. 

If compile succeeds, it returns a non-NULL pointer whose value depends on 
expbuf. If expbuf is non-NULL, compile returns a pointer to the byte after the last 
byte in the compiled regular expression. The length of the compiled regular 
expression is stored in reglengtJi. Otherwise, compile returns a pointer to the 
space allocated by malloc. 

If an error is detected when compiling the regular expression, a NULL pointer is 
returned from compile and regerrno is set to one of the non-zero error numbers 
indicated below: 
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ERROR 



MEANING 



11 
16 
25 
36 
41 
42 
43 
44 
45 
46 
49 
50 



Range endpoint too large. 
Bad number. 
"\digit" out of range. 
Illegal or missing delimiter. 
No remembered search string. 
\{^\) imbalance. 
Too many \(. 

More than 2 numbers given in \{ -\}. 
} expected after \. 

First number exceeds second in \{ '^X}. 
[ ] imbalance. 

Regular expression overflow. 



The call to step is as follows: 

step (string, expbuf) 

The first parameter to step is a pointer to a string of characters to be checked for 
a match. This string should be null-terminated. 

The parameter expbuf is the compiled regular expression obtained by a call of the 
function conpile. 

The function step returns non-zero if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a match, two 
external character pointers are set as a side effect to the call to step. The variable 
set in step is loci, loci is a pointer to the first character that matched the regu- 
lar expression. The variable loc2 points to the character after the last character 
that matches the regular expression. Thus if the regular expression matches the 
entire line, loci points to the first character of string and lc>c2 points to the null 
at the end of string. 

The purpose of step is to step through the string argument until a match is 
found or until the end of string is reached. If the regular expression begins with 
^, step tries to match the regular expression at the beginning of the string only. 

The function advance has the same arguments and side effects as step, but it 
always restricts matches to the beginning of the string. 

If one is looking for successive matches in the same string of characters. Iocs 
should be set equal to loc2, and step should be called with string equal to loc2. 
Iocs is used by commands like ed and sed so that global substitutions like 
s/y*//g do not loop forever, and is NULL by default. 

The external variable nbra is used to determine the number of subexpressions in 
the compiled regular expression, braslist and braelist are arrays of character 
pointers that point to the start and end of the nbra subexpressions in the 
matched string. For example, after calling step or advance with string sabcdef g 
and regular expression \(abcdef\), braslist [0] will point at a and brael- 
ist [0] will point at g. These arrays are used by commands like ed and sed for 
substitute replacement patterns that contain the \n notation for subexpressions. 
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Note that it isn't necessary to use the external variables regerrno, nbra, loci, 
loc2 Iocs, braelist, and braslist if one is only checking whether or not a 
string matches a regular expression. 

EXAMPLES 

The following is similar to the regular expression code from grep: 
♦include <rege^r.h> 

if (compile (*argv, (char *)0, (char *)0) == (char *)0) 
regerr (regerrno) ; 

if (stepdinebuf , e^qpbuf ) ) 
succeed 0 ; 

SEE ALSO 

regexp(5). 

ed(l), grep(l), sed(l) in the Use/s Reference Manual. 



10/89 



Page 3 



8tr(3G) 



str(3G) 



NAME 

str: strf ind, strrspn, strtrns - string manipulations 

SYNOPSIS 

cc [flag ...] file ... -Igen [library . . .] 

tinclude <libgen.h> 

int strfind (const char *asl, const char '*'as2) ; 

char *strrspn (const char '•'string, const char *tc) ; 

char * strtrns (const char *str, const char *old, const char *new, 
char *result); 

DESCRIPTION 

strfind returns the offset of the second string, as2, if it is a substring of string 
asl. 

strrspn returns a pointer to the first character in the string to be trimmed (all 
characters from the first character to the end of string are in ic). 

strtrns transforms str and copies it into result. Any character that appears in 
old is replaced with the character in the same position in new. The new result is 
returned. 

EXAMPLES 

/* find pointer to substring "hello" in asl */ 
i = strfind (asl, "hello"); 

/* trim junk from end of string */ 
s2 = strrspn(sl, "*?#$%"); 
*s2 = '\0'; 

/* transform lower case to upper case */ 
al[] = "abcdefghijklmnopqrstuvwxyz"; 
a2[] » "ABCDEFGHIJKLMNOPQRSTUVWXYZ"; 
s2 = strtrns (si, al, a2, s2) ; 

SEE ALSO 

string(3C). 

DIAGNOSTICS 

If the second string is not a substring of the first string strfind returns -1. 
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NAME 

strccpy: streadd, strcadd, strecpy - copy strings, compressing or expanding 
escape codes 

SYNOPSIS 

cc [flag .,.]file ... -Igen llibrary . . .] 

♦include <libgen.h> 

char * strccpy (char * output, const char * input ) / 

char *strcadd (char * output, const char * input); 

char *strecpy (char *output, const char *input, const char 
♦exceptions) ; 

char *streadd (char *output, const char * input, const char 
♦exceptions) ; 

DESCRIPTION 

strccpy copies the input string, up to a null byte, to the output string, compress- 
ing the C-language escape sequences (for example, \n, \001) to the equivalent 
character. A null byte is appended to the output. The output argument must 
point to a space big enough to accommodate the result. If it is as big as the space 
pointed to by input it is guaranteed to be big enough, strccpy returns the output 
argimient. 

strcadd is identical to strccpy, except that it returns the pointer to the null byte 
that terminates the output. 

strecpy copies the input string, up to a null byte, to the output string, expanding 
non-graphic characters to their equivalent C-language escape sequences (for 
example, \n, \001). The output argument must point to a space big enough to 
accommcxiate the result; four times the space pointed to by input is guaranteed to 
be big enough (each character could become \ and 3 digits). Characters in the 
exceptions string are not expanded. The exceptions argimient may be zero, mean- 
ing all non-graphic characters are expanded, strecpy returns the output argu- 
ment 

streadd is identical to strecpy, except that it returns the pointer to the null byte 
that terminates the output. 

EXAMPLES 

/♦ expand all but newline and tab ♦/ 
strecpy ( output, input, "\n\t" ); 

/* concatenate and compress several strings */ 
cp = strcadd ( output, input 1 ); 
cp = strcadd ( cp, input2 ); 
cp - strcadd ( cp, inputs ); 

SEE ALSO 

stringOC), str(3G). 
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NAME 

intro - introduction to the math library 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

♦include <inath.h> 
DESCRIPTION 

This section describes the functions in the math library, libia Declarations for 
these functions may be obtained from the #include file math.h. Several gen- 
erally useful mathematical constants are also defined there [see introO) and 
xnath(5)]. 

The math library is not automatically loaded by the C compilation system; use 
the -1 option to cc to access the library as shovsm in above. 

libm contains the full set of double-precision routines plus some single-precision 
routines (designated by the suffix f ) that give better performance with less preci- 
sion. Selected routines are hand-optimized for performance. The optimized rou- 
tines include sin, cos, tan, atan, atan2, exp, log, loglO, pow, and sqrt and 
their single-precision equivalents. 

DEFINITIONS 

See introO) for C language definitions. 

FILES 

LIBDIR usually /usr/ccs/lib 

L7BD/R/libm.a 

SEE ALSO 

cc(l), intro(2), introO), inath(5). 

The "Roating Point Operations" chapter in the Programme/s Guide: ANSI C and 
Programming Support Tools. 

DIAGNOSTICS 

Error handling varies according to compilation mode. Under the -Xt (default) 
option to cc, these functions return the conventional values 0, ±HUGE, or NaN 
when the function is undefined for the given arguments or when the value is not 
representable. In the -Xa and -Xc compilation modes, ±HUGE_VAL is returned 
instead of ±HUGE. (HUGE__yAL and HUCS are defined in math.h to be infinity and 
the largest-magnitude single-precision number, respectively.) In every case, the 
external variable errno [see intro(2)] is set to the value EDOM or ERANGE, 
although the value may vary for a given error depending on compilation mode. 
See the table under matherr(3M) below. 
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NAME 

bessel; jO, jl, jn, yO, yl, yn - Bessel functions 

SYNOPSIS 

cc [flag . . .] file . . . -Im [library . . .] 

tinclude <math.h> 
double jO (double x) ; 
double jl (double x) / 
double jn (int n, double x) ; 
double yO (double x) ; 
double yl (double x) ; 
double yn (int n, double x) ; 
DESCRIPTION 

jO and jl return Bessel functions of x of the first kind of orders 0 and 1, respec- 
tively, jn returns the Bessel function of x of the first kind of order n . 

yO and yl return Bessel functions of x of the second kind of orders 0 and 1, 
respectively, yn returns the Bessel function of x of the second kind of order n. 
The value of x must be positive. 

SEE ALSO 

inatherrOM). 

DIAGNOSTICS 

Non-positive arguments cause yO, yl, and yn to return the value -HUGE and to set 
errno to EDOM. In addition, a message indicating DOMAIN error is printed on the 
standard error output. 

Arguments too large in magnitude cause jO, jl, yO, and yl to return 0 and to set 
errno to ERANGE. In addition, a message indicating TLOSS error is printed on the 
standard error output. 

Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the function matherr. When the -Xa or -Xc compilation 
options are used, HUGE__VAL is returned instead of HUGE and no error messages 
are printed. 
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NAME 

erf, erf c - error function and complementary error function 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

♦include <nath.h> 
double erf (double x) ; 
double erf c (double x) ; 

DESCRIPTION 

erf returns the error function of x, defined as 

erfc, which returns 1.0 - erf{x), is provided because of the extreme loss of rela- 
tive accuracy if erf (jc) is called for large x and the result subtracted from 1.0 
(e.g., for jc = 5, 12 places are lost). 

SEE ALSO 

exp(3M). 
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NAME 

exp, expf, cbrt, log, logf, loglO, loglOf, pow, powf, sqrt, sqrtf - exponen- 
tial, logarithm, power, square root functions 

SYNOPSIS 

cc [flag . . .] file . . . -im [library . . .] 

cc -O -Ksd [flag ...]file ... -J sf m [library . . .] 

tinclude <math.h> 

double exp (double x) / 

float ejqpf (float x) ; 

double cbrt (double x) ; 

double log (double x) ; 

float logf (float x) ; 

double loglO (double x) ; 

float loglOf (float x) ; 

double pow (double x, double y) ; 

float powf (float x, float y); 

double sqrt (double x) ; 

float sqrtf (float x) ; 

DESCRIPTION 

exp and expf return ^. 

cbrt returns the cube root of x. 

log and logf return the natural logarithm of x. The value of x must be positive. 

loglO and loglOf return the base ten logarithm of x. The value of x must be 
positive. 

pow and powf return jc^. \i x is 0, y must be positive. If x is negative, y must be 
an integer. 

sqrt and sqrtf return the non-negative square root of x. The value of x may 
not be negative. 

SEE ALSO 

hypotOM), matherrOM), sinh(3M). 

DIAGNOSTICS 

exp and expf return HUGE when the correct value would overflow, or 0 when the 
correct value would underflow, and set errno to ERANGE. 

log, logf, loglO, and loglOf return -HUGE and set ermo to EDOM when x is 
non-positive. A message indicating DCDMAIN error is printed on standard error. 

pow and powf return 0 and set errno to EDCM when x is 0 and y is non-positive, 
or when x is negative and y is not an integer. In these cases, a message indicat- 
ing DOMAIN error is printed on standard error. When the correct value for pow or 
powf would overflow or underflow, these functions return ±HUGE or 0, respec- 
tively, and set errno to ERANGE. 
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sqrt and sqrtf return 0 and set ermo to EDOM when x is negative. A message 
indicating DOMAIN error is printed on standard error. 

Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the function xnatherr. When the -Xa or -Xc compilation 
options are used, HUGE_yAL is returned instead of HUGE and no error messages 
are printed. In these compilation modes, pow and powf return 1, with no error, 
when both x and y are 0; when jc is 0 and y is negative, they return -HUGE__VAL 
and set errno to EDOM Under -Xc, log and logf return -HUGE^VAL and set 
errno to ERANGE when x is 0. Under -Xc, sqrt and sqrtf return NaN when x is 
negative. 



Page 2 



10/89 



floor (3M) 



floor (3M) 



NAME 

floor, floorf, ceil, ceilf, cq^sign, fmod^ fmodf, fabs, fabsf, rint, 
remainder - floor, ceiling, remainder, absolute value functions 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

♦include <math.h> 
double floor (double x) ; 
float f loorf (float x) ; 
double ceil (double x) ; 
float ceilf (float x) ; 
double copysign (double x, double y) ; 
double fmod (double x^ double y) ; 
float fnodf (float x, float y) ; 
double fabs (doisble x) ; 
float fabsf (float x) ; 
double rint (double x) ; 
double remainder (double x, double y) ; 
DESCRIPTION 

floor and f loorf return the largest integer not greater than x. ceil afid ceilf 
return the smallest integer not less than x. 

copysign returns x but with the sign of y. 

fmod and fmodf return the floating point remainder of the division of x by y. 
More p-ecisely, they return the number / with the same sign as x, such #i€tt x = iy 
+ / for some integer i, and | / 1 < | y | . 

fabs and fabsf return the absolute value of jc, | jc | . 

rint returns the nearest integer value to its floating point argument jc as a 
double-precision floating point number. The returned value is roimded according 
to the currently set machine rounding mode. If round-to-nearest (the default 
mode) is set and the difference between the function argtiment and the rounded 
result is exactly 0.5, then the result will be rounded to the nearest even integer. 

remainder returns the floating point remainder of the division of ;i: by y. More 
precisely, it returns the value r = x - yn, where n is the integer nearest the exact 
value x/y. Whenever \ n - x/y\ = Yi, then n is even. 

SEE ALSO 

abs(3C), matherrOM). 

DIAGNOSTICS 

fmod and fmodf return x when y is 0 and set errno to EDOM remainder returns 
NaN when y is 0 and sets errno to EDOM. In both cases, except in compilation 
modes -Xa or -Xc, a message indicating DOMAIN error is printed on standard 
error. Except under -Xc, these error-handling procedures may be changed with 
the function matherr. 
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NAME 

gamna, Igamna - log gamma function 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

♦include <math.h> 

double gaima (double x); 

double Iganina (double x) ; 

extern int signgaxn; 

DESCRIPTION 

gamna and Igaxnna return 

ln(|r(jc)|) 

where H x) is defined as 

0 

The sign of FCjc) is returned in the external integer signgaia The argument x 
may not be a non-positive integer. 

The following C program fragment might be used to calculate T: 

if ((y » gaxnna(x)) > ihjaxdoubie) 

error ( ) ; 
y = signgam * e3qp(y); 

where LNJMAXDOUBLE is the least value that causes e:j^ to return a range error, 
and is defined in the values. h header file. 

SEE ALSO 

exp(3M), matherrOM), values(5). 

DIAGNOSTICS 

For non-positive integer arguments HUGE is returned and errno is set to EDOM. A 
message indicating SING error is printed on the standard error output. 

If the correct value would overflow, gaitita and Igaxnna return HUGE and set 
errno to ERANGE. 

Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the function matherr. When the -Xa or -Xc compilation 
options are used, HUGE^VMj is returned instead of HUGE and no error messages 
are printed. 
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NAME 

hypot - Euclidean distance function 

SYNOPSIS 

cc [flag .,.] file ... -Im [library . . .] 

tinclude <inath.h> 

double hypot (double x, double y) ; 

DESCRIPTION 

hypot returns 

sqrt(x * X + y * y) 
taking precautions against unwarranted overflows. 

SEE ALSO 

xnatherr(3M). 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and sets errno to 

Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the fimction matherr. When the -Xa or -Xc compilation 
options are used, HUGEJVAL is returned instead of HUGE. 
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NAME 

matherr - error-handling function 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

finclude <inath.h> 
int matherr (struct exception *x) ; 
DESCRIPTION 

matherr is invoked by functions in the math libraries when errors are detected. 
Note that matherr is not invoked when the -Xb compilation option is used. 
Users may define their own procedures for handling errors, by including a func- 
tion named matherr in their programs, matherr must be of the form described 
above. When an error occurs, a pointer to the exception structure x will be 
passed to the user-supplied matherr function. This structure, which is defined in 
the math.h header file, is as follows: 

struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

}; 

The element type is an integer describing the type of error that has occurred, 
from the following list of constants (defined in the header file): 

DOMAIN argument domain error 

SING argument singularity 

OVERFLOW overflow range error 

UNDERFLOW underflow range error 

TLOSS total loss of significance 

PLOSS partial loss of significance 

The element name points to a string containing the name of the function that 
incurred the error. The variables argl and arg2 are the arguments with which 
the function was invoked, retval is set to the default value that will be returned 
by the function unless the user's matherr sets it to a different value. 

If the user's matherr function returns non-zero, no error message will be printed, 
and errno will not be set. 

If matJierr is not supplied by the user, the default error-handling procedures, 
described with the math functions involved, will be invoked upon error. These 
procedures are also summarized in the table below. In every case, ermo is set to 
EDOM or ERANGE and the program continues. 
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Default Error Handling Procedures 




Types of Errors 


type 


DOMAIN 


SING 


OVERFLOW 


UNDERFLOW 


TLOSS 


PLOSS 


errno 


EDOM 


EDOM 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 

yO, yl, yn (arg ^ 0) 


H-H 








M, 0 




EXP.EXPF: 




- 


H 


0 




- 


LOG, LOGIO: 
LOGF, LOGIQF: 

(arg < 0) 

(arg = 0) 


M,-H 
M,-H 


- 


- 


- 


- 


- 


POW, POWF: 
neg *♦ non-int 
0 *♦ non-pos 


M, 0 
M, 0 


- 

- 


±H 

- 


0 

- 


- 


- 

- 


SQRT, SQRTF: 


M, 0 


- 


- 


- 


- 


- 


FMOD, FMODF: 
(arg2 = 0) 


M, X 


- 


- 


- 


- 


- 


REMAINDER: 
(arg2 = 0) 




- 


- 


- 


- 


- 


GAMMA, LGAMMA: 


- 




H 


- 


- 


- 


HYPOT: 






H 








SINH,SINHF: 


- 


- 


±H 


- 


- 


- 


COSacOSHF: 






H 








ASnsI, ACQS, ATAN2: 
ASINF, ACOSF, ATAISI2F: 


M,0 












ACOSH: 


M,N 












ATANH: 
(1 argi >1) 
(1 argI = 1) 


M,N 


HN 
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Abbreviations 


M 


Message is printed (not with the -Xa or -Xc options). 


H 


HUGE is returned (HDGE_VAL with the -Xa or -Xc options). 


-H 


-HUGE is returned (-HUGEJVMi with the -Xa or -Xc options). 


±H 


HUGE or -HUGE is returned. 




(HUGE_yAL or -HUGE^VAL with the -Xa or -Xc options). 


0 


0 is returned. 


X 


argl is returned. 


N 


NaN is returned. 



EXAMPLE 

♦include <math.h> 
♦include <stdio.h> 
♦include <stdlib.h> 
♦include <strin9.h> 



int 

matherr (register struct exception ♦x) ; 
{ 

switch (x->type) { 
case DOMAIN: 

/* change sqrt to return sqrt (-argl) , not 0 */ 

if ( ! strcnp (x->naine , " sqrt " ) ) { 

x->retval = sqrt (-x->argl) ; 

return (0) ; /* print message and set errno */ 

} 

case SING: 

/* all other domain or sing errors, print message */ 
/* and abort */ 

£print£(stderr, "domain error in %s\n", x->name) ; 
abort( ); 
case PLOSS: 

/* print detailed error message */ 

fprintf (stderr, "loss of significance in %s (%g)=%g\n", 

x->name, x->argl, x->retval) ; 
return (1) ; /♦ take no other action */ 

} 

return (0); /* all other errors, execute default procedure */ 

} 

NOTES 

Error handling in -Xa and -Xt modes [see cc(l)] is described more completely on 
individual math library pages. 
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NAME 

sinh, sinhf, cosh, coshf, tanh, tarhf, asinh, acosh, atanh - hyperbolic func- 
tions 

SYNOPSIS 

cc Ifiag ...]file ... -Im [library . . .] 

♦include <roath.h> 
double sinh (double x) ; 
float sinhf (float x) ; 
double cosh (double x) ; 
float coshf (float x) ; 
doi2ble tanh (double x) ; 
float tanhf (float x) ; 
double asinh (double x); 
double acosh (double x) ; 
double atanh (double x); 
DESCRIPTION 

sinh, cosh, and tanh and the single-precision versions sinhf, coshf, and tanhf 
return, respectively, the hyberbolic sine, cosine, and tangent of their argument. 

asinh, acosh, and atanh return, respectively, the inverse hyperolic sine, cosine, 
and tangent of their argument. 

SEE ALSO 

xnatherrOM). 

DIAGNOSTICS 

sinh, sinhf, cosh, and coshf return HUGE (and sinh and sinhf may return 
-HUGE for negative x) when the correct value would overflow and set errno to 
ERANGE. 

acosh returns NaN and sets errno to EDOM when the argument x is less than 1. A 
message indicating DC3MAIN error is printed on the standard error output. 

atanh returns NaN and sets errno to EDOM if | jc | > 1. If | jc | = 1, a message 
indicating SING error is printed on the standard error output; if | x\ > 1 the mes- 
sage will indicate DOMAIN error. 

Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the function inatherr. When the -Xa or -Xc compilation 
options are used, HUGE__yAL is returned instead of HUGE and no error messages 
are printed. 
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NAME 

trig; sin, sinf, cos, cosf, tan, tanf, asin, asinf, acos, acosf, atcm, atanf, 
atan2, atan2f - trigonometric functions 

SYNOPSIS 

cc [flag ...] file ... -Im [library . . .] 

cc -O -Ksd [flag ...]file... -J sfm [library . . .] 
♦include <inath.h> 
double sin (double x) ; 
float sinf (float x) ; 
double cos (double x) ; 
float cosf (float x) ; 
double tan (double x) ; 
float tanf (float x) ; 
double asin (double x) ; 
float asinf (float x) ; 
doi:ible acos (double x) ; 
float acosf (float x) ; 
double atan (double x) ; 
float atanf (float x) ; 
double atcLn2 (double double x) ; 
float atan2f (float y, float x) ; 
DESCRIPTION 

sin, cos, and tan and the single-precision versions sinf, cosf, and tanf return, 
respectively, the sine, cosine, and tangent of their argument, x, measured in radi- 
ans. 

asin and asinf return the arcsine of x, in the range [-7i/2,+7c/2]. 

acos and acosf return the arccosine of x, in the range [0,+7i]. 

atan and atanf return the arctangent of x, in the range (-7c/2,+7c/2). 

atan2 and atan2f return the arctangent of y/x, in the range (-7t,-t-7i], using the 
signs of both arguments to determine the quadrant of the return value. 

SEE ALSO 

inatherr(3M). 

DIAGNOSTICS 

If the magnitude of the argument of asin, asinf, acos, or acosf is greater than 
1, or if both arguments of atan2 or atan2f are 0, 0 is returned and errno is set 
to EDOM. In addition, a message indicating DOMAIN error is printed on the stan- 
dard error output. 
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Except when the -Xc compilation option is used, these error-handling procedures 
may be changed with the function roatherr. When the -Xa or -Xc compilation 
options are used, no error messages are printed. 
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NAME 

assert - verify program assertion 

SYNOPSIS 

♦include <assert.h> 

void assert (int expression) ; 



assert (3X) 



DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is executed, 
if expression is false (zero), assert prints 

Assertion failed: expression, file Jtyz, line nnn 

on the standard error output and aborts. In the error message, xyz is the name of 
the source file and nnn the source line number of the assert statement. The 

latter are respectively the values of the preprocessor macros FILE and 

LINE . 

Compiling with the preprocessor option -DNDEBUG [see cc(l)], or with the prepro- 
cessor control statement #define NDEBUG ahead of the #include <assert.h> 
statement, will stop assertions from being compiled into the program. 

SEE ALSO 

cc(l), abortOC). 

NOTES 

Since assert is implemented as a macro, the expression may not contain any 
string literals. 
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NAME 

crypt - password and file encryption functions 
SYNOPSIS 

CO Iflag ...] file ... -Icrypt [library . . .] 
♦include <crypt.h> 

char * crypt (const char *]cey, const char *salt); 

void set key (const char ♦key) ; 

void encrypt (char *block, int flag) ; 

char *des_jcrypt (const char *key, const char *salt); 

void des_setkey (const char *key) ; 

void des_encrypt (char *block, int flag) / 

int run_setkey (int *p, const char *key) ; 

int runjcrypt (long offset, char *buffer, unsigned int count, 
int *p); 

int crypt^close (int *p) ; 

DESCRIPTION 

des^crypt is the password encryption function. It is based on a one-way hash- 
ing encryption algorithm with variations intended (among other things) to frus- 
trate use of hardware implementations of a key search. 

key \s dL user's typed password, salt is a two-character string chosen from the set 
[a-zA~Z0-9 . /]; this string is used to perturb the hashing algorithm in one of 4096 
different ways, after which the password is used as the key to encrypt repeatedly 
a constant string. The returned value points to the encrypted password. The first 
two characters are the salt itself. 

The des_setkey and des_encrypt entries provide (rather primitive) access to the 
actual hashing algorithm. The argument of des__setkey is a character array of 
length 64 containing only the characters with numerical value 0 and 1. If this 
string is divided into groups of 8, the low-order bit in each group is ignored, 
thereby creating a 56-bit key that is set into the machine. This key is the key that 
will be used with the hashing algorithm to encrypt the string block with the fimc- 
tion des_encrypt. 

The argument to the des^encrypt entry is a character array of length 64 contain- 
ing only the characters with numerical value 0 and 1. The argument array is 
modified in place to a similar array representing the bits of the argument after 
having been subjected to the hashing algorithm using the key set by des__setkey. 
If fiag is zero, the argument is encrypted; if non-zero, it is decrypted. 

Note that decryption is not provided in the international version of crypt. The 
international version is part of the C Development Set, and the domestic version 
is part of the Security Administration Utilities. If decryption is attempted with 
the international version of desjencrypt, an error message is printed. 
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crypt, setkey, and encrypt are front-end routines that invoke desjrypt, 
desjetkey, and des _encryj)t respectively. 

The routines run__setkey and nm_crypt are designed for use by applications 
that need cryptographic capabilities [such as ed(l) and vi(l)] that must be com- 
patible with the crypt (1) user-level utility, runjsetkey establishes a two-way 
pipe connection with the crypt utility, using key as the password argument, 
runjcrypt takes a block of characters and transforms the cleartext or ciphertext 
into their ciphertext or cleartext using the crypt utility, offset is the relative byte 
position from the beginning of the file that the block of text provided in block is 
coming from, count is the number of characters in block, and connection is an 
array containing indices to a table of input and output file streams. When encryp- 
tion is firushed, cryptjclose is used to terminate the connection with the crypt 
utility. 

runjsetkey returns -1 if a connection with the crypt utility cannot be esta- 
blished. This result will occur in international versions of the UNIX system in 
which the crypt utility is not available. If a null key is passed to run__setkey, 0 
is returned. Otherwise, 1 is returned, runjcrypt returns -1 if it cannot write 
output or read input from the pipe attached to crypt. Otherwise it returns 0. 

The program must be linked with the object file access routine library 
libcrypt . a. 

SEE ALSO 

getpassOO, passwd(4). 

crypt(l), login(l), passwd(l) in the User's Reference Manual. 
DIAGNOSTICS 

In the international version of cryptOX), a flag argument of 1 to encrypt or 
desjencrypt is not accepted, and errno is set to ENOSYS to indicate that the 
functionality is not available. 

NOTES 

The return value in crypt points to static data that are overwritten by each call. 
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NAME 

libwindows - windowing terminal function library 
SYNOPSIS 

cc [flag ,.,]file ... -Iwindows lUbrary . . .] 
int openagent (void) ; 

int New (int cntlfd, int origin__x, int origin_y, 
int corner_x, int comer_y) ; 

int Newlayer (int cntlfd, int origin^x, int origin_y, 
int corner_x, int comer__y) ; 

int cpenchan (int chan) ; 

int Runlayer (int chan^ char *coninand) ; 

int Current (int cntlfd, int chan) ; 

int Delete (int cntlfd^ int chan) ; 

int Top (int cntlfd, int chan) ; 

int Bottom (int cntlfd, int chan) ; 

int Move (int cntlfd, int chan, int origin_x, int origin__y) ; 

int Reshape (int cntlfd, int chan, int origin_x, int origin_y, 
int corner_x, int comer__y); 

int Exit (int cntlfd); 

DESCRIPTION 

This library of routines enables a program running on a host UNIX system to per- 
form windowing terminal functions [see layers(l)]. 

The openagent routine opens the control channel of the xt(7) channel group to 
which the calling process belongs. Upon successful completion, cpenagent 
returns a file descriptor that can be passed to any of the other libwindows rou- 
tines except openchan and Runlayer. (The file descriptor can also be passed to 
the close system call.) Otherwise, the value -1 is returned. 

The New routine creates a new layer with a separate shell. The originjc, origin j/, 
corner _x, and corner _y arguments are the coordinates of the layer rectangle. If all 
the coordinate arguments are 0, the user must define the layer's rectangle interac- 
tively. The layer appears on top of any overlapping layers. The layer is not 
made current (i.e., the keyboard is not attached to the new layer). Upon success- 
ful completion. New returns the xt(7) channel number associated with the layer. 
Otherwise, the value -1 is returned. 

The Newlayer routine creates a new layer without executing a separate shell. 
Otherwise it is identical to New, described above. 

The openchan routine opens the channel argument chan which is obtained from 
the New or Newlayer routine. Upon successful completion, openchan returns a 
file descriptor that can be used as input to write(2) or close(2). Otherwise, the 
value -1 is returned. 
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The Runlayer routine runs the specified command in the layer associated with the 
channel argument chart. This layer is usually a layer previously created with 
Newlayer. Any processes currently attached to this layer will be killed, and the 
new process will have the environment of the layers process. 

The Current routine makes the layer associated with the channel argument chan 
current (i.e., attached to the keyboard). 

The Delete routine deletes the layer associated with the channel argument chan 
and kills all host processes associated with the layer. 

The Top routine makes the layer associated with the channel argument chan 
appear on top of all overlapping layers. 

The Bottcsm routine puts the layer associated with the channel argument chan 
under all overlapping layers. 

The Move routine moves the layer associated with the channel argument chan 
from its current screen location to a new screen location at the origin point 
{originjc, origin_y). The size and contents of the layer are maintained. 

The Reshc^ routine reshapes the layer associated with the channel argument 
chan. The arguments originjc, origin_y, comer _x, and corner jf are the new coordi- 
nates of the layer rectangle. If all the coordinate arguments are 0, the user is 
allowed to define the layer's rectangle interactively. 

The Exit routine causes the layers program to exit, killing all processes associ- 
ated with it. 

FILES 

UL/BDIR/libwindows . a windowing terminal function library 
ULIBDIR usually /usr/lib 

SEE ALSO 

close(2), write(2), j agent (5). 

layer s(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, Runlayer, Current, Delete, Top, Bottonv Move, 
Reshape, and Exit return 0, while openagent. New, Newlayer, and openchan 
return values as described above under each routine. If an error occurs, -1 is 
returned. 

NOTES 

The values of layer rectangle coordinates are dependent on the type of terminal. 
This dependency affects the routines that pass layer rectangle coordinates: Move, 
New, Newlayer, and Reshape. Some terminals will expect these numbers to be 
passed as character positions (bytes); others will expect the information to be in 
pixels (bits). 
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For example, for the AT&T 5620 DMD terminal. New, Newlayer, and Reshape 
take minimum values of 8 (pixels) for origin jc and origin and maximum values 
of 792 (pixels) for corner _x and 1016 (pixels) for comer j^. The minimum layer 
size is 28 by 28 pixels and the maximum layer size is 784 by 1008 pixels. 

It is recommended that applications use /dev/xt/?? [0-7] instead of 
/dev/xt?? [0-7] when accessing the xt driver. 



10/89 



Page 3 



maillock(3X) 



malllock(3X) 



NAME 

maillock - manage lockfile for user's mailbox 

SYNOPSIS 

cc [flag ...] file ... -Imail [library . . .] 

♦include <maillock.h> 

int maillock (const char *user, int retrycnt) ; 
int mailunlock (void) ; 
DESCRIPTION 

The maillock function attempts to create a lockfile for the user's mailfile. If a 
lockfile already exists, maillock assumes the contents of the file is the process ID 
(as a null-terminated ASQI string) of the process that created the lockfile (presum- 
ably with a call to maillock). If the process that created the lockfile is still alive, 
maillock will sleep and try again retrycnt times before returning with an error 
indication. The sleep algorithm is to sleep for 5 seconds times the attempt 
number. That is, the first sleep will be for 5 seconds, the next sleep will be for 10 
seconds, etc. until the number of attempts reaches retrycnt. When the lockfile is 
no longer needed, it should be removed by calling mailunlock. 

user is the login name of the user for whose mailbox the lockfile will be created, 
maillock assumes that users' mailfiles are in the "standard" place as defined in 
maillock . h. 

RETURN VALUE 

The following return code definitions are contained in maillock. h. 

♦define L_SUCCESS 0 /* Lockfile created or removed */ 

♦define L_NAMELEN 1 /* Recipient name > 13 chars ♦/ 

♦define LJIMPIOCK 2 /* Can't create tmp file ♦/ 

♦define LJIMPWRITE 3 /* Can't write pid into lockfile */ 

♦define L_M2VXTRYS 4 /* Failed after retrycnt attempts ♦/ 

♦define L ERROR 5 /* Check errno for reason */ 



FILES 



NOTES 



L/BD JR/llib-mail . In 
LJBD7R/mail.a 
/var/mail/* 
/var/mail/* . lock 

mailunlock will only remove the lockfile created from the most previous call to 
maillock. Calling maillock for different users without intervening calls to 
mailunlock will cause the initially created lockfile(s) to remain, potentially block- 
ing subsequent message delivery until the current process finally terminates. 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinf o - memory allocator 
SYNOPSIS 

cc [flag ,..] file ... -Imalloc [library . . .] 
♦include <stdlib.h> 
void *malloc (size_t size) 
void free (void *ptr) 
void *realloc (void *ptr, size_t size) 
void *calloc (size_J: nelem^ size_t elsize) 
♦include <inalloc.h> 
int roallopt (int cind, int value) 
struct mallinfo inallinfo (void) 
DESCRIPTION 

malloc and free provide a simple general-purpose memory allocation package. 

malloc returns a pointer to a block of at least size bytes suitably aligned for any 
use. 

The argument to free is a pointer to a block previously allocated by malloc; 
after free is performed this space is made available for further allocation, and its 
contents have been destroyed (but see mallopt below for a way to change this 
behavior). If j)tr is a null pointer, no action occurs. 

Undefined results occur if the space assigned by malloc is overrun or if some 
random ntmiber is handed to free. 

realloc changes the size of the block pointed to by ptr to size bytes and returns 
a pointer to the (possibly moved) block. The contents are unchanged up to the 
lesser of the new and old sizes. If ptr is a null pointer, realloc behaves like mal- 
loc for the specified size. If size is zero and ptr is not a null pointer, the object it 
points to is freed. 

calloc allocates space for an array of nelem elements of size elsize. The space is 
initialized to zeros. 

mallopt provides for control over the allocation algorithm. The available values 
for and are: 

M_MXFAST Set maxfast to value. The algorithm allocates all blocks below the 
size of maxfast in large groups and then doles them out very quickly. 
The default value for maxfast is 24. 

MJJLBLKS Set numlblks to value. The above mentioned "large groups" each 
contain numlblks blocks, numlblks must be greater than 0. The 
default value for numlblks is 100. 

MjGRAIN Set grain to value. The sizes of all blocks smaller than maxfast are 
considered to be rounded up to the nearest multiple of grain . grain 
must be greater than 0. The default value of grain is the smallest 
number of bytes that will allow alignment of any data type. Value 
will be rounded up to a multiple of the default when grain is set. 
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MJKEEP Preserve data in a freed block until the next nalloc, realloc, or 
calloc. This option is provided only for con\patibility with the old 
version of xnalloc and is not recommended. 

These values are defined in the nalloch header file. 

inallopt may be called repeatedly, but may not be called after the first small 
block is allocated. 

inallinf o provides instrumentation describing space usage. It returns the struc- 
ture: 

struct inallinfo { 

int arena; /* total space in arena */ 

int ordblks; /* ninnber of ordinary blocks */ 
int srnblks; /* nuntoer of small blocks */ 
int hblkhd; /* space in holding block headers */ 
int hblks; /* number of holding blocks ♦/ 

int usirblks; /♦ space in small blocks in use */ 
int fsirblks; /♦ space in free small blocks */ 
int uordblks; /♦ space in ordinary blocks in use */ 
int f ordblks; /* space in free ordinary blocks */ 
int keepcost; /* space penalty if keep option */ 
/* is used */ 

} 

This structure is defined in the malloc.h header file. 

Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), mallocOC). 

DIAGNOSTICS 

malloc, realloc, and calloc return a NULL pointer if there is not enough avail- 
able memory. When realloc returns NULL, the block pointed to by ptr is left 
intact. If itallopt is called after any allocation or if and or value are invalid, 
non-zero is returned. Otherwise, it returns zero. 

NOTES 

Note that unlike mallocOC), this package does not preserve the contents of a 
block when it is freed, imless the MJCEEP option of mallopt is used. 

Undocumented features of mallocOC) have not been duplicated. 

Function prototypes for malloc, realloc, calloc and free are also defined in 
the <malloc.h> header file for compatibility with old applications. New applica- 
tions should include <stdlib.h> to access the prototypes for these functions. 
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NAME 

sputl, sgetl - access long integer data in a machine-independent fashion 

SYNOPSIS 

cc [flag ,,,]file -lid [library . . .] 

♦include <ldfcn.h> 

void sputl (long value ^ char *buf fer) ; 
long sgetl (const char *buf f er) ; 
DESCRIPTION 

sputl takes the four bytes of the long integer value and places them in memory 
starting at the address pointed to by buffer. The ordering of the bytes is the same 
across all machines. 

sgetl retrieves the four bytes in memory starting at the address pointed to by 
buffer and returns the long integer value in the byte ordering of the host machine. 

The combination of sputl and sgetl provides a machine-independent way of 
storing long numeric data in a file in binary form without conversion to charac- 
ters. 
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NAME 

intro - introduction to file formats 
DESCRIPTION 

This section outlines the formats of various files. The C structure declarations for 
the file formats are given where applicable. Usually, the header files containing 
these structure declarations Ccin be found in the directories /usr/ include or 
/usr/include/sys. For inclusion in C language programs, however, the syntax 
♦include <filename.h> or #include <3Y3/filemme.h> should be used. 
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NAME 

a . out - ELF (Executable and Linking Format) files 

SYNOPSIS 

♦include <elf .h> 

DESCRIPTION 

The file name a. out is the default output file name from the link editor, ld(l). 
The link editor will make an a . out executable if there were no errors in linking. 
The output file of the assembler, as(l), also follows the format of the a. out file 
although its default file name is different. 

Programs that manipulate ELF files may use the library that elf(3E) describes. 
An overview of the file format follows. For more complete information, see the 
references given below. 



Linking View 



Execution View 



ELF header 



Program header table 
optional 



Section 1 



Section n 



Section header table 



ELF header 



Program header table 



Segment 1 



Segment 2 



Section header table 
optional 



An ELF header resides at the beginning and holds a "road map" describing the 
file's organization. Sections hold the bulk of object file information for the link- 
ing view: instructions, data, symbol table, relocation information, and so on. 
Segments hold the object file information for the program execution view. As 
shown, a segment may contain one or more sections. 

A program header table, if present, tells the system how to create a process 
image. Files used to build a process image (execute a program) must have a pro- 
gram header table; relocatable files do not need one. A section header table con- 
tains information describing the file's sections. Every section has an entry in the 
table; each entry gives information such as the section name, the section size, etc. 
Files used during linking must have a section header table; other object files may 
or may not have one. 

Although the figure shows the program header table immediately after the ELF 
header, and the section header table following the sections, actual files may differ. 
Moreover, sections and segments have no specified order. Only the ELF header 
has a fixed position in the file. 

When an a. out file is loaded into memory for execution, three logical segments 
are set up: the text segment, the data segment (initialized data followed by unini- 
tialized, the latter actually being initialized to all O's), and a stack. The text seg- 
ment is not writable by the program; if other processes are executing the same 
a . out file, the processes will share a single text segment. 
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The data segment starts at the next maximal page boimdary past the last text 
address. (If the system supports more than one page size, the "maximal page" is 
the largest supported size.) When the process image is created, the part of the 
file holding the end of text and the beginning of data may appear twice. The 
duplicated chunk of text that appears at the beginning of data is never executed; 
it is duplicated so that the operating system may bring in pieces of the file in 
multiples of the actual page size without having to realign the beginning of the 
data section to a page boundary. Therefore, the first data address is the sum of 
the next maximal page boundary past the end of text plus the remainder of the 
last text address divided by the maximal page size. If the last text address is a 
multiple of the maximal page size, no duplication is necessary. The stack is 
automatically extended as required. The data segment is extended as requested 
by the brk(2) system call. 

SEE ALSO 

as(l), cc(l), ld(l), brk(2), elf(3E). 

The "Object Files" chapter in the Programmer's Guide: ANSI C and Programming 
Support Tools. 
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NAME 

ar - archive file format 

SYNOPSIS 

♦include <ar.h> 

The archive command ar(l) is used to combine several files into one. Archives 
are used mainly as libraries to be searched by the link editor ld(l). 

Each archive begins with the archive magic string. 

♦define armag " !<arch>\n" /* magic string */ 

♦define SARMAG 8 /* length of magic string */ 

Following the archive magic string are the archive file members. Each file 
member is preceded by a file member header which is of the following format: 

♦define ARFMAG ""\n" /* header trailer string */ 

struct arjhdr /♦ file member header */ 

{ 

/* terminated file member name */ 
/* file member date */ 
/* file member user identification */ 
/* file member group identification */ 
/* file member mode (octal) */ 
/* file member size */ 
/* header trailer string */ 



char 


ar__name[16] ; 


char 


ar_date[12] / 


char 


arjiiid[6] ; 


char 


ar_gid[6] ; 


char 


ar_mode[8] ; 


char 


ar_size[10] ; 


char 


ar_fmag[2] ; 



All information in the file member headers is in printable ASCII. The numeric 
information contained in the headers is stored as decimal numbers (except for 
arjnode which is in octal). Thus, if the archive contains printable files, the 
archive itself is printable. 

If the file member name fits, the arjiame field contains the name directly, and is 
terminated by a slash (/) and padded with blanks on the right. If the member's 
name does not fit, arjiame contains a slash (/) followed by a decimal representa- 
tion of the name's offset in the archive string table described below. 

The ar_date field is the modification date of the file at the time of its insertion into 
the archive. Common format archives can be moved from system to system as 
long as the portable archive command ar(l) is used. 

Each archive file member begins on an even byte boundary; a newline is inserted 
between files if necessary. Nevertheless, the size given reflects the actual size of 
the file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 
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Each archive that contains object files [see a.out(4)] includes an archive symbol 
table. This symbol table is used by the link editor ld(l) to determine which 
archive members must be loaded during the link edit process. The archive sym- 
bol table (if it exists) is always the first file in the archive (but is never listed) and 
is automatically created and /or updated by ar. 

The archive symbol table has a zero length name (i.e., ar_name[0] is V, 
ar__naine[l]=' etc.). All "words" in this symbol table have four bytes, using 
the machine-independent encoding shown below. (All machines use the encoding 
described here for the symbol table, even if the machine's "natural" byte order is 
different.) 





0 


1 


2 


3 


0x01020304 


01 


02 


03 


04 



The contents of this file are as follows: 

1. The number of symbols. Length: 4 bytes. 

2. The array of offsets into the archive file. Length: 4 bytes * "the number of 
symbols". 

3. The name string table. Length: ar_size - 4 bytes ♦ ("the number of sym- 
bols" -f 1). 

As an example, the following symbol table defines 4 symbols. The archive 
member at file offset 114 defines name and object. The archive member at file 
offset 426 defines function and a second version of name. 



Offset 


+0 


+1 


+2 


+3 




0 


4 


4 offset entries 


4 


114 


name 


8 


114 


object 


12 


426 


function 


16 


426 


name 


20 


n 


a 


m 


e 




24 


\0 


o 


b 


j 




28 


e 


c 


t 


\o 




32 


f 


u 


n 


c 




36 


t 


i 


o 


n 




40 


\o 


n 


a 


m 




44 


e 


\o 









The number of symbols and the array of offsets are managed with sgetl and 
sputl. The string table contains exactly as many null terminated strings as there 
are elements in the offsets array. Each offset from the array is associated with the 
corresponding name from the string table (in order). The names in the string 
table are all the defined global s3TObdls found in the common object files in the 
archive. Each offset is the location of the archive header for the associated sym- 
bol. 
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SEE ALSO 

ar(l), ld(l), stripd), sputlOX), a.out(4). 

NOTES 

stripd) will remove all archive symbol entries from the header. The archive 
R5nTibol entries must be restored via the -ts options of the ar(l) command before 
the archive can be used with the link editor ld(l). 
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NAME 

core - format of core image file 
DESCRIPTION 

The UNIX system writes out a core image of a terminated process when any of 
various errors occur. See signal(2) for the list of reasons; the most common are 
memory violations, illegal instructions, bus errors, and user-generated quit sig- 
nals. The core image is called core and is written in the process's working direc- 
tory (provided it can be; normal access controls apply). A process with an effec- 
tive user ID different from the real user ID will not produce a core image. 

The first section of the core image is a copy of the system's per-user data for the 
process, including the registers as they were at the time of the fault. The size of 
this section depends on the parameter usize, which is defined in <sys/param.h>. 
The remainder represents the actual contents of the user's core area when the 
core image was written. If the text segment is read-only and shared, or separated 
from data space, it is not dumped. 

The format of the information in the first section is described by the user struc- 
ture of the system, defined in <sys/user.h>. Not included in this file are the 
locations of the registers. These are outlined in <sys/reg.h>. 

SEE ALSO 

sdb(l), setuid(2), signal(2). 

crashdM) in the System Administrator's Reference Manual. 
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NAME 

limits - header file for implementation-specific constants 

SYNOPSIS 

♦include <limits.h> 

DESCRIPTION 

The header file limits. h is a list of minimal magnitude limitations imposed by a 
specific implementation of the operating system. 



ARG MAX 


5120 


/ 


may lAnatYi drnummtifi tin aic^g ^/ 


CHAR BIT 


8 




max # of bits in a "char" */ 


cvasi MAX 


127 




max valua of a "ehar" ♦ / 


CHAR MIN 


-128 


lit 


min valiiA of^ a "rjhai"" ♦/ 


CHILD MAX 


25 


/>«> 


may of nforiAAaAa dap iisai" 4^/ 


cue TCK 


100 






DBL DIG 


15 


/ 


rJicrita of onAfision of a "doiiblA" */ 

\A ■ J ■ vJL fc^X^wXO WX Ci \4fc^ lift /X w ^/ 


DBL MAX 


1 . 7 976 931348 623157E+308 


/* 


may (iecimal value of a "double"*/ 


DBL^MIN 


2 . 2250738585072014E-308 


/* 


min decimal value of a "double"*/ 


FCHR MAX 


1048576 


/* 


max size of a file in bytes */ 


FLT DIG 


6 


/* 


digits of precision of a "float" */ 


PLT MAX 


3 . 40282347e+38F 


/* 


max decimal value of a "float" */ 


FLT MIN 


1.17549435E-38F 


/* 


min decimal value of a "float" */ 


int'max 


2147483647 


/* 


max value of an "int" */ 


INT MIN 


(-2147483647-1) 


/* 


min value of an "int" */ 


LINK MAX 


1000 


/* 


max # of links to a single file */ 


LOGNAtd MAX 


8 


/* 


max # of characters in a login name */ 


LONG BIT 


32 


/* 


# of bits in a "long" */ 


LONG MAX 


2147483647 


/♦ 


max value of a "long int" */ 


laSG MIN 


(-2147483647-1) 


/* 


min value of a "long int" */ 


MAX CANON 


256 


/* 


max bytes in a line for canonical 






processing */ 


MAX_INPUT 


512 


/♦ 


max size of a diar iiput buffer */ 


MBJLENJ4AX 


5 


/* max # of bytes in a multibyte 






character */ 


NAMBJ1AX 


14 


/* 


max # of characters in a file name */ 


NGROUPSJAX 


16 


/♦ 


max # of groups for a user */ 


NL_ARGMAX 


9 


/* 


max value of "digit" in calls to the 






NLS printf 0 azxi scanf () ♦/ 


NLJiANGMAX 


14 


/* 


max # of bytes in a LANG name */ 


NLJMSGMAX 


32767 


/* 


max message nunober */ 


NL_NMAX 


1 


/* max # of bytes in N-to-1 mapping 






characters */ 


NLJSETMAX 


255 


/* max set nunber 


NLJTEXTMAX 


255 


/* 


max # of bytes in a message string */ 


NZERO 


20 


/* default process priority */ 


OPENJAX 


60 


/♦ 


max # of files a process can have 






open */ 


PASSJAX 


8 


/* 


max # of characters in a password */ 
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PATHJMAX 


256 


/* 


max # of characters in a path name 


PIDJ4AX 


30000 


/♦ 


max value for a process "Sb *l 


PIPB_BUF 


5120 


/♦ 


max # bytes atomic in write to a pipe */ 


PIPEJAX 


5120 


/* 


max # bytes written to a pipe 






in 


a write ♦/ 


SCHARJAX 


127 


/* 


max value of a "signed char" */ 


SCHARjmi 


(-128) 


/* 


min value of a "signed char" *l 


SHRTJ4AX 


32767 


/* 


max value of a "short int" 


SHRTJCN 


(-32768) 


/* 


min value of a "short int" */ 


STD_BI1C 


1024 


/* 


# bytes in a physical I/O block */ 




9 


/* 


4.0 size of utsname elements */ 






h 


also defined in sys/utsname .h *l 


SYSPIDJ1AX 


1 


h 


max pid of system processes */ 


TMPJOVX 


17576 


/* 


max # of unique names generated 






by 


tnpnam *i 


UCHARMAX 


255 


/♦ 


max value of an "unsigned char" *i 


UIDJ1AX 


60000 


/* 


max value for a user or groi:^ ID */ 


UINT_MftX 


4294967295 


/* 


max value of an "unsigned int" */ 


ULONGJCOC 


4294967295 


/♦ 


max value of an "unsigned long int" ^/ 


USHRT_MaX 


65535 


/* 


max value of an "unsigned short int" */ 


USIJIMC 


4294967295 


/* 


max decimal value of an "unsigned" */ 


WORD BIT 


32 


/* 


« of bits in a "word" or "int" */ 



The following POSIX definitions are the most restrictive values to be used by a 
POSIX conformant application. Conforming implementations shall provide values 
at least this large. 



_POSIX_ARG_MAX 


4096 


h max length of arguments to exec */ 


JP0SIXJCHILD__MMC 


6 


/* max # of processes per user ID */ 


_POSIX_LINK_MAX 


8 


/* max # of links to a single file ^1 


J?C)SIXJ«XJCAN0N 


255 


/■f max # of bytes in a line of input 


_POSIX_MAX_INPUT 


255 


max # of bytes in terminal 






input queue */ 


_POSIXJIlM;jflVX 


14 


h # of bytes in a filename 


_POSIX_NGRO0PSJBVX 


0 


/* max # of groi:qps in a process */ 


JPOSIXjOPENf_MMC 


16 


h max # of files a process can have open 


_POSlX_PATHJiaX 


255 


h max # of characters in a pathname *l 


_POSIX_PIPE_BUF 


512 


h max # of bytes atomic in write 






to a pipe */ 
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NAME 

sccsf ile - format of SCCS file 
DESCRIPTION 

An SCCS (Source Code Control System) file is an ASCII file. It consists of six logi- 
cal parts: the checksim\, the delta table (contains information about each delta), 
user names (contains login names and /or numerical group IDs of users who may 
add deltas), flags (contains definitions of internal keywords), comments (contains 
arbitrary descriptive information about the file), and the body (contains the actual 
text lines intermixed with control lines). 

Throughout an SCCS file there are lines which begin with the ASCII SOH (start of 
heading) character (octal 001). This character is hereafter referred to as the con- 
trol character and will l>e represented graphically as @. Any line described below 
that is not depicted as beginning with the control character is prevented from 
beginning with the control character. 

Entries of the form DDDDD represent a five-digit string (a number between 00000 
and 99999). 

Each logical part of an SCCS file is described in detail below. 
Checksum 

The checksum is the first line of an SCCS file. The form of the line is: 
^hDDDDD 

The value of the checksum is the sum of all characters, except those of the first 
line. The @h provides a magic number of (octal) 064001, depending on byte 
order. 

Delta table 

The delta table consists of a variable number of entries of one of the following 
forms: 

@s DDDDD/DDDDD/DDDDD 

<type><SCCS ID> yrlmo/da hr:mi:se <pgmr> DDDDD DDDDD 
@i DDDDD . . . 
@x DDDDD . . . 
0g DDDDD . . . 
@m <MR number> 

@c <comments> . . . 

@e 

The first line (@s) contains the number of lines inserted/deleted/unchanged, 
respectively. The second line (0d) contains the type of the delta (normal: D or 
removed: R), the SCCS ID of the delta, the date and time of creation of the delta, 
the login name corresponding to the real user ID at the time the delta was 
created, and the serial numbers of the delta and its predecessor, respectively. 

The @i, @x, and @g lines contain the serial numbers of deltas included, excluded, 
and ignored, respectively. These lines are optional. 
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The @m lines (optional) each contain one MR number associated with the delta; the 
@c lines contain comments associated with the delta. The @e line ends the delta 
table entry. 

User names 

The list of login names and/or numerical group IDs of users who may add deltas 
to the file, separated by new-lines. The lines containing these login names and/or 
numerical group IDs are surrounded by the bracketing lines @u and @U. An 
empty list allows anyone to make a delta. Any line starting with a ! prohibits 
the succeeding group or user from making deltas. 

Flags 

Kejwords used internally. See admind) for more information on their use. Each 
flag line takes the form: 

@f <flag> <optiond text> 

The following flags are defined: 

@f t <type of program> 
6f V <program mme> 
0f i <keyv>ord $tring> 
@£ b 

@£ m <module name> 

f <floor> 
@f c <ceiling> 
@f d <default'Sid> 
@f n 
@f j 

@f 1 <lock'releases> 
0f q <user defined> 
0f z <reserved for use in interfaces> 

The t flag defines the replacement for the %Y% identification keyword. The v flag 
controls prompting for MR ntimbers in addition to comments; if the optional text 
is present it defines an MR number validity checking program. The i flag con- 
trols the warning/error aspect of the "No id keywords" message. When the i 
flag is not present, this message is only a warning; when the i flag is present, this 
message causes a fatal error (the file will not be "gotten", or the delta will not be 
made). When the b flag is present the -b keyletter may be used on the get com- 
mand to cause a branch in the delta tree. The m flag defines the first choice for 
the replacement text of the %M% identification keyword. The f flag defines the 
floor release; the release below which no deltas may be added. The c flag defines 
the ceiling release; the release above which no deltas may be added. The d flag 
defines the default SID to be used when none is specified on a get command. 
The n flag causes delta to insert a null delta (a delta that applies no changes) in 
those releases that are skipped when a delta is made in a new release (e.g., when 
delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). The absence of the 
n flag causes skipped releases to be completely empty. The j flag causes get to 
allow concurrent edits of the same base SID. The 1 flag defines a list of releases 
that are locked against editing. The q flag defines the replacement for the %Q% 
identification keyword. The z flag is used in specialized interface programs. 
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NAME 

timezone - set default system time zone 

SYNOPSIS 

/etc/TIMEZONE 

DESCRIPTION 

This file sets and exports the time zone environmental variable TZ. 
This file is "dotted" into other files that must know the time zone. 

EXAMPLES 

/etc/TIMEZONE for the east coast: 

# Time Zone 
TZ=EST5EDT 
e:^rt TZ 

SEE ALSO 

ctimeOO, environ(5). 

rc2(lM), prof ile(4) in the System Administrator's Reference Manual, 
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NAME 

strf time - language specific strings 
DESCRIPTION 

There can exist one printable file per locale to specify its date and time formatting 
information. These files must be kept in the directory 
/usr/lib/locale/<Ioc»Ie>/LCjriME. The contents of these files are: 

1. abbreviated month names (in order) 

2. month names (in order) 

3. abbreviated weekday names (in order) 

4. weekday names (in order) 

5. default strings that specify formats for locale time (%X) and 

locale date (%x). 

6. default format for cftime, if the argument for cftime is zero or null. 

7. AM (ante meridian) string 

8. PM (post meridian) string 

Each string is on a line by itself. All white space is significant. The order of the 
strings in the above list is the same order in which they must appear in the file. 

EXAMPLE 

/usr/lib/locale/C/LC_TIME 

Jan 
Feb 

January 
February 

Sun 
Mon 

Sunday 
Monday 

%H:%M:%S 
%in/%d/%y 

%a %b %d %T %Z %Y 

m 

PM 

FILES 

/usr/lib/locale/</ocak>/LCjriME 
SEE ALSO 

ctimeOC), setlocaleOQ, strftimeOQ. 
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Comments 

Arbitrary text is surrounded by the bracketing lines @t and @T. The comments 
section t)^ically will contain a description of the file's purpose. 

Body 

The body consists of text lines and control lines. Text lines do not begin with the 
control character, control lines do. There are three kinds of control lines: insert, 
delete, and end, represented by: 

61 DDDDD 
0D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number corresponding to the delta for 
the control line. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l). 
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NAME 

intro - introduction to miscellany 
DESCRIPTION 

This section describes miscellaneous facilities such as macro packages, character 
set tables, etc. 
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NAME 

utirp, wtirp - utmp and wtmp entry formats 

SYNOPSIS 

♦include <ut:itp.h> 

DESGRIPTION 

These files, which hold user and accounting information for such commands as 
who, write, and login, have the following structure, defined in <utirp.h>: 

♦define UTl«__Fll£ "/etc/utnp" 
♦define WM_FILE "/etc/wtnp" 
♦define ut name ut user 



struct 



utnp { 



char 


utjuser[8] ; 


/* 


user login name */ 


char 


ut__id[4] ; 




/sbin/inittab id (created by process 








that puts entry in utirp) */ 


char 


ut_line[12]; 


/* 


device name (console, Inxx) */ 


short 


ut_pid; 


/* 


process id */ 


short 


ut__type; 


/♦ 


type of entry */ 


struct 


exit status { 






short e_ternu.nation; 


/* 


process termination st:atus */ 


short ejexit; 


/* 


process exit status */ 


} ut exit; 


/* 


exit status of a process 








marked as DEADJPRCX:ess */ 


time_t 


ut_tiine; 


/♦ 


time entry was made */ 



}; 



/* Definitions for utjtype */ 

♦define EMPTY 0 

♦define RUNJiVL 1 

♦define BOOT_TIME 2 

♦define OLD_TIME 3 

♦define NEWJTIME 4 

♦define INIT__PROCESS 5 

♦define LOGIN_PROCESS 6 

♦define USER__PRCX3:SS 7 

♦define DEAD__PROCESS 8 

♦define ACCOUNTING 9 
♦define UTMZVXTYPE 



/* process spawned by "init" */ 
/* a "getty" process waiting for login */ 
/* a user process */ 



ACCOUNTING /* max legal value of ut_type */ 
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/* special strings or fontats used in the "ut__line" field when */ 

/* accounting for something other than a process */ 

/* no string for the ut_line field can be more than 11 chars + */ 

/* a null character in length */ 

♦define RUNLVLJ6G "run-level %c" 
♦define BOOT_MSG "system boot" 
♦define OTM JGG "old time" 
♦define NTBCJCG "new time" 

FILES 

/etc/utxrp 
/etc/wtnp 

SEE ALSO 

login(l), who(l), write(l) in the User's Reference Manual 
getut(3C). 
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NAME 

ascii - map of ASCII character set 
DESCRIPTION 

ascii is a map of the ASQI character set, giving both octal and hexadecimal 
equivalents of each character, to be printed as needed. It contains: 



|000 


nul 


001 


soh 


002 


stx 


003 


etx 


004 eot 


005 


enq 


006 ack 


007 bel 1 


joio 


bs 


Oil 


ht 


012 


nl 


013 


vt 


014 np 


015 


cr 


016 so 


017 si I 


1020 


die 


|021 


del 


|022 


dc2 


023 


dc3 


|024 dc4 


i025 


nak 


026 syn 


027 etb 1 


j030 


can 


031 


em 


032 


sub 


033 


esc 


034 fs 


035 


gs 


036 rs 


037 us 


1 040 


sp 


041 


f 


042 




043 


# 


|044 $ 


1 045 % 


046 & 


047 1 


1050 


( 


051 


) 


|052 


* 


053 




054 , 


|055 




056 . 


057 / 1 


j060 


0 


061 


1 


062 


2 


063 


3 


064 4 


065 


5 


066 6 


067 7 1 


1 070 


8 


071 


9 


|072 




073 




|074 < 


|075 




076 > 


077 ? I 


1 100 


@ 


101 


A 


102 


B 


103 


C 


104 D 


|105 


E 


106 F 


107 G 1 


1 110 


H 


111 


I 


1 112 


J 


|113 K 


114 L 


|115 M 


116 N 


117 O 1 


1 120 


P 


121 


Q 


1 122 


R 


123 


S 


124 T 


|125 U 


126 V 


127 W 1 


1 130 


X 


131 


Y 


1 132 


Z 


133 


[ 


134 \ 


|135 


] 


136 * 


137 _ 1 


1 140 




141 


a 


1 142 


b 




c 


144 d 


|145 


e 


146 f 


147 g I 


1 150 


h 


151 


i 


152 


j 


153 


k 


154 1 


1155 


m 


156 n 


157 o 1 


1 160 


P 


161 


q 


1 162 


r 


163 


s 


164 t 


|165 


u 


166 V 


167 w 1 


1 170 


X 


171 


y 


1 172 


z 


173 


{ 


174 1 


|175 


} 


176 ~ 


177 del I 


1 00 


nul 


01 


soh 


02 


stx 


03 


etx 


04 eot 


1 05 


enq 


06 ack 


07 bel 1 


1 08 


bs 


09 


ht 


Oa 


nl 


Ob 


vt 


Oc np 


1 Od 


cr 


Oe so 


Of si I 


1 10 


die 


11 


del 


12 


dc2 


13 


dc3 


14 dc4 


1 15 


nak 


16 syn 


17 etb 1 


1 18 


can 


19 


em 


1 la 


sub 


lb 


esc 


Ic fs 


Id 


gs 


le rs 


I If us 


1 20 


sp 


21 


j 


1 22 




23 


# 


24 $ 


25 


% 


26 &c 


OFT ^ 

27 1 


1 


\ 




) 


1 za 




2b 


+ 


1 2c , 


2d 




ze . 


Of/ 1 

2f / 1 


1 30 


0 


1 31 


1 


32 


2 


33 


3 


1 34 4 


1 35 


5 


36 6 


37 7 I 


1 38 


8 


39 


9 


3a 




3b 




3c < 


1 3d 




3e > 


3f ? 1 


1 40 


@ 


41 


A 


42 


B 


43 


C 


44 D 


45 


E 


46 F 


47 G 1 


1 48 


H 


49 


I 


1 4a 


J 


4b 


K 


i 4c L 


4dM 


4e N 


4f O 1 


1 50 


P 


51 


Q 


1 52 


R 


53 


S 


1 54 T 


1 55 U 


56 V 


57 W 1 


1 58 


X 


59 


Y 


5a 


Z 


5b 


[ 


5c \ 


i 5d 


] 


5e " 


5f 1 


1 60 




61 


a 


1 62 


b 


63 


c 


1 64 d 


I 65 


e 


66 f 


67 g 1 


1 68 


h 


69 


1 


6a 


j 


6b 


k 


1 6c 1 


6d m 


6e n 


6f o 1 


1 70 


P 


71 


q 


1 72 


r 


73 


s 


1 74 t 


1 75 


u 


76 V 


77 w 1 


1 78 


X 


79 


y 


1 7a 


z 


7b 


{ 


1 7c 1 


1 7d } 


7e - 


7f del 1 



FILES 

/usr/pub/ascii 
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NAIUIE 

environ - user environment 
DESCRiPTION 

When a process begins execution, exec routines make available an array of strings 
called the environment [see exec(2)]. By convention, these strings have the form 
vanabk=valtie, for example, PATH=/bin : /usr/bin. These environmental vari- 
ables provide a way to make information about a program's environment avail- 
able to programs. The following environmental variables can be used by applica- 
tions and are expected to be set in the target run-time environment. 

HOME The name of the user's login directory, set by login(l) from the 

password file (see passwd(4)). 

LANG The string used to specify localization information that allows users 

to work with different national conventions. The setlocale(3C) 
fimction looks for the LANG environment variable when it is called 
with "" as the locale argument. LANG is used as the default locale if 
the corresponding environment variable for a particular category is 
unset. 

For example, when setlocaleO is invoked as 

setlocale(LC_CTYPE, ""), 

setlocaleO will query the LCjCTYPE environment variable first to 
see if it is set and non-null. If LC_CTYPE is not set or null, then set- 
localeO will check the LANG environment variable to see if it is set 
and non-null. If both LANG and LCJCTYPE are unset or null, the 
default C locale will be used to set the LCjCTYPE category. 

Most commands will invoke 

setlocale (LC_ALL, "") 

prior to any other processing. This allows the command to be used 
with different national conventions by setting the appropriate 
environment variables. 

The following environment variables are supported to correspond 
with each category of setlocale(3C): 

LCjCOLLATE This category specifies the collation sequence being 
used. The information corresponding to this 
category is stored in a database created by the 
oolltbl(lM) command. This environment variable 
affects strcollOC) and strxfnn(3C). 

LCjCTYPE This category specifies character classification, char- 
acter conversion, and widths of multibyte charac- 
ters. The information corresponding to this 
category is stored in a database created by the 
chrtJ^KlM) command. The default C locale 
corresponds to the 7-bit ASCII character set. This 
environment variable is used by ctypeOC), 
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irbchar(3C), and many commands; for example, 
cat(l), ed(l), ls(l), and vi(l). 

LC_MONETARY This category specifies the monetary symbols and 
delimiters used for a particular locale. The informa- 
tion corresponding to this category is stored in a 
database created by the rnontbl(lM) command. 
This enviroimient variable is used by 
localeconv(3C). 

LC_NUMERIC This category specifies the decimal and thousands 
delimiters. The information corresponding to this 
category is stored in a database created by the 
chrtJDl(lM) command. The default C locale 
corresponds to " . " as the decimal delimiter and no 
thousands delimiter. This environment variable is 
used by localeconv(3C), printfOC), and 
strtod(3C). 

LCjriME This category specifies date and time formats. The 

information corresponding to this category is stored 
in a database specified in strftime(4). The default 
C locale corresponds to U.S. date and time formats. 
This environment variable is used by many com- 
mands and functions; for example: at(l), calen- 
dar(l), dated), strftimeOC), and getdate(3C). 

MSGVERB Controls which standard format message components fmtxnsg selects 
when messages are displayed to stderr [see fmtmsgOC)]. 

SEVJLEVEL Define severity levels and associate and print strings with them in 
standard format error messages [see addseverity(3C) and 
fmtxnsgOOl. 

PATH The sequence of directory prefixes that sh(l), timed), niced), 

nohvqpd), etc., apply in searching for a file known by an incomplete 
path name. The prefixes are separated by colons ( : ). logind) sets 
PATH=/bin:/usr/bin. (For more detail, see shd).) 

TERM The kind of terminal for which output is to be prepared. This infor- 

mation is used by commands, such as mmd) or vid), which may 
exploit special capabilities of that terminal. 

TZ Time zone irtformation. 

The contents of the environment variable named TZ are used by the 
functions ctime(3C), localtixneO (see ctimeOO), strftime(3C) 
and niktiine(3C) to override the default timezone. If the first char- 
acter of TZ is a colon (:), the behavior is implementation defined, 
otherwise TZ has the form: 

stdoffset [ dst [ offset ] , [ start [ /time ],end[ /time ] ] ] 
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Where: 
std and dst 

Three or more bytes that are the designation for the standard 
(std) and daylight savings time (dst) timezones. Only std is 
required, if dst is missing, then daylight savings time does 
not apply in this locale. Upper- and lower-case letters are 
allowed. Any characters except a leading colon (:), digits, a 
comma (,), a. minus (-) or a plus (+) are allowed. 

offset Indicates the value one must add to the local time to arrive 
at Coordinated Universal Time. The offset has the form: 

hh [ : mm [ : ss ] ] 

The minutes (mm) and seconds (ss) are optional. The hour 
(hh) is required and may be a single digit. The offset follow- 
ing std is required. If no offset follows dst , daylight savings 
time is assumed to be one hour ahead of standard time. One 
or more digits may be used; the value is always interpreted 
as a decimal number. The hour must be between 0 and 24, 
and the minutes (and seconds) if present between 0 and 59. 
Out of range values may cause unpredictable behavior. If 
preceded by a the timezone is east of the Prime Meri- 
dian; otherwise it is west (which may be indicated by an 
optional preceding sign). 

start /time, end /time 

Indicates when to change to and back from daylight savings 
time, where start/time describes when the change from stan- 
dard time to daylight savings time occurs, and end/time 
describes when the change back happens. Each time field 
describes when, in current local time, the change is made. 

The formats of start and end are one of the following: 

Jn The Julian day n (1 < n < 365). Leap days are 
not counted. That is, in all years, February 28 is 
day 59 and March 1 is day 60. It is impossible 
to refer to the occasional February 29. 

n The zero-based Julian day (0 < n < 365). Leap 
days are counted, and it is possible to refer to 
February 29. 

Mm.nJ , 

The d day, (0 < < 6) of week n of month m 
of the year (1 < n < 5, 1 < m < 12), where week 
5 means "the last ^^-day in month m" which 
may occur in either the fourth or the fifth 
week). Week 1 is the first week in which the 
d day occurs. Day zero is Sunday. 
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Implementation specific defaults are used for start and end if 
these optional fields are not given. 

The time has the same format as offset except that no leading 
sign (' or "+") is allowed. The default, if time is not given 
is 02:00:00. 

Further names may be placed in the environment by the export command and 
name=value arguments in sh(l), or by exec(2). It is imwise to conflict with cer- 
tain shell variables that are frequently exported by .profile files: MAIL, PSl, 
PS2, IFS [see prof ile(4)]. 

SEE ALSO 

strftime(4), passwd(4), profile(4) in the System Administrator's Reference 
Manual. 

chrtbl(lM), colltbl(lM), montbl(lM), exec(2), addseverity(3C), ctixne(3C), 
ctype(3C), fmtmsgOC), getdate(3C), localeconv(3C), ntocharOC), mktimeOC), 
printf (3C), strcoll(3C), strftime(3C), strtod(3C), strxf nn(3C), strftiine(4), 
tiinezone(4). 

cat(l), dated), ed(l), ls(l), login(l), nice(l), nohup(l), sh(l), sort(l), time(l), 
vi(l) in the User's Reference Manual. 

mmd) in the DOCUMENTER'S WORKBENCH Software Technical Discussion and 
Reference Manual. 
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NAME 

f cntl - file control options 

SYNOPSIS 

# include <fcntl.h> 

DE3CR8PTBON 

The <fcntl.h> header defines the following requests and arguments for use by 
the functions fcntl [see fcntl(2)] and open [see open(2)]. 

Values for and used by fcntl (the following values are unique): 
Duplicate file descriptor 
Get file descriptor flags 
Set file descriptor flags 
Get file status flags 
Set file status flags 
Get record locking information 
Set record locking information 
Set record locking informations- 
wait if blocked 



F 


_DUPFD 


f' 


J3ETFD 


f" 


JSETFD 


f" 


JSETFL 


f" 


SETFL 


f' 


GETLK 


f' 


""SETLK 


f' 


"SETLKW 



File descriptor flags used for fcntl: 

FDjCLOEXEC Close the file descriptor upon 

execution of an exec function [see exec(2)] 

Values for l_type used for record locking with fcntl 
(the following values are unique): 

F_RDLCK Shared or read lock 

FJJNLCK Unlock 

F_WRLCK Exclusive or write lock 

The following three sets of values are bitwise distinct: 
Values for of lag used by open: 

OjCREAT Create file if it does not exist 

0__EXCL Exclusive use flag 

0_NOCTTY Do not assign controlling tty 

OJTRUNC Truncate flag 

File status flags used for open and fcntl: 
0__APPEND Set append mode 

0_NDELAY Non-blocking mode 
OJJONBLOCK Non-blocking mode (POSIX) 
OJSYNC Synchronous writes 

Mask for use with file access modes: 

0 ACCMODE Mask for file access modes 
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File access modes used for open and f cntl: 
p_RDONLY Open for reading only 
0_RDWR Open for reading and writing 

OJWRONLY Open for writing only 

The structure flock describes a file lock. It includes the following members: 

short l_type; /* Type of lock */ 

short Ijwhence; /* Flag for starting offset */ 

off_t l__start; /* Relative offset in bytes */ 

offj: l_len; /* Size; if 0 then until EOF */ 

long l_sysid; /* Returned with FjSETLK */ 

pid_t l_pid; /* Returned with FjSETLK */ 

SEE ALSO 

creat(2), exec(2), f cntl(2), open(2). 
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NAME 

jagent - host control of windowing terminal 

SYNOPSIS 

♦include <sys/ jioctl.h> 

int ioGtl (int cntlfd,- JAQENT,. Sarg) ; 
DESCRIPTION 

The ioctl system call, when performed on an xt(7) device with the JAGENT 
request, allows a host program to send information to a windowing terminal. 

ioctl has three arguments: 

cntlfd the xt(7) control channel file descriptor 

JAGENT the xt ioctl request to invoke a windowing terminal agent routine. 

&arg the address of a bagent structure, defined in <sys/j ioctl. h> as fol- 
lows: 

struct 
int 
char 
char 

}; 

The src pointer must be initialized to point to a byte string that is 
sent to the windowing terminal. See layers(5) for a list of JAGENT 
strings recognized by windowing terminals. Likewise, the dest 
pointer must be initialized to the address of a buffer to receive a byte 
string returned by the terminal. When ioctl is called, the size argu- 
ment must be set to the length of the src string. Upon return, size is 
set by ioctl to the length of the destination byte string, dest. 

SEE ALSO 

ioctl(2), libwindows(3X), layers(5). 
xt(7) in the Programmer's Guide: STREAMS. 

DIAGNOSTICS 

Upon successful completion, a non-negative value, the size of the destination byte 
string, is returned. If an error occurs, -1 is returned. 



bagent { 

size; /* size of src in & dest out */ 
*src; /* the source byte string */ 
*dest; /* the destination byte string */ 
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NAME 

layers ~ protocol used between host and windowing terminal under layers(l) 
DESCRIPTION 

Layers are asynchronous windows supported by the operating system in a win- 
dowing terminal. Communication between the UNIX System processes and ter- 
minal processes under the layers command [see layers(l)] occurs via multi- 
plexed channels managed by the respective operating systems using a protocol as 
specified in xtproto(5). 

The contents of packets transferring data between a UNIX System process and a 
layer are asymmetric. Data sent from the UNIX System to a particular terminal 
process are undifferentiated and it is up to the terminal process to interpret the 
contents of packets. 

Control information for terminal processes is sent via channel 0. Process 0 in the 
windowing terminal performs the designated functions on behalf of the process 
connected to the designated channel. These packets take the form: 

command, channel 

except for JTIMOM and JAGENT information, which takes the form 

command, data ... 

The commands are the bottom eight bits extracted from the following ioctl(2) 
codes: 

JBOOT Prepare to load a new terminal program into the designated layer. 

JTERM Kill the downloaded layer program, and restore the default window 
program. 

JTIMOM Set the timeout parameters for the protocol. The data consist of four 
bytes in two groups: the value of the receive timeout in milliseconds 
(the low eight bits followed by the high eight bits) and the value of the 
transmit timeout (in the same format). 

JZOMBOOT Like JBOOT, but do not execute the program after loading. 

JAGENT Send a source byte string to the terminal agent routine and wait for a 
reply byte string to be returned. 

The data are from a bagent structure [see jagent(5)] and consist of a 
one-byte size field followed by a two-byte agent command code and 
parameters. Two-byte integers transmitted as part of an agent com- 
mand are sent with the high-order byte first. The response from the 
terminal is generally identical to the command packet, with the two 
command bytes replaced by the return code: 0 for success, -1 for 
failure. Note that the routines in the libwindows(3X) library all send 
parameters in an agentrect structure. The agent command codes and 
their parameters are as follows: 

AJIEWLAYER followed by a two-byte channel number and a rec- 
tangle structure (four two-byte coordinates). 
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AJCORRENT followed by a two-byte channel number. 

AJ)ELETE followed by a two-byte channel number. 

A_TOP followed by a two-byte channel number. 

A_BOTT0M followed by a two-byte channel number. 

A_MOVE followed by a two-byte channel number and a point 

to move to (two two-byte coordinates). 

A_RESHAPE followed by a two-byte channel number and the new 
rectangle (four two-byte coordinates). 

A_JIEW followed by a two-byte channel number and a rec- 

tangle structure (four two-byte coordinates). 

AJEXIT no parameters needed. 

A_ROMVERSION no parameters needed. The response packet contains 
the size byte, two-byte return code, two unused 
bytes, and the parameter part of the terminal ID 
string (e.g., 8; 7; 3) . 

JXTPROTO Set xt protocol type [see xtproto(5)l. The data consist of one byte 
specifying maximum size for the data part of regular xt packets sent 
from the host to the terminal. This number may be lower than the 
number returned by AJCTPROTO at lower baud rates or if the -m option 
was specified upon invocation of layers(l). A size of 1 specifies net- 
work xt protocol. 

Packets from the windowing terminal to the UNIX System all take the following 
form: 

command, data ... 

The single-byte commands are as follows: 

C_SENDCHAR Send the next byte to the UNIX System process. 

CJJEW Create a new UNIX System process group for this layer. 

Remember the window size parameters for this layer. 
The data for this command is in the form described by 
the jwinsize structure. The size of the window is 
specified by two 2-byte integers, sent low byte first. 

CJDNBLK Unblock transmission to this layer. There are no data for 

this command. 

CJDELETE Delete the UNIX System process group attached to this 

layer. There are no data for this command. 

C_EXIT Exit. Kill all UNIX System process groups associated 

with this terminal and terminate the session. There are 
no data for this command. 

CJ)EFUNCT Layer program has died, send a terminate signal to the 

UNIX System process groups associated with this termi- 
nal. There are no data for this command. 
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CJSENDNCHARS 
C RESHAPE 



C_NOFLOW 
CJfESFLOW 

FILES 

/usr/include/windows . h 
/usr/include/sys/ jioctl . h 

SEE ALSO 

layers(l), libwindowsOX), jagent(5), xtproto(5). 
xt(7) in the Programmer's Guide: STREAMS. 
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The rest of the data are characters to be passed to the 
UNIX System process. 

The layer has been reshaped. Change the window size 
parameters for this layer. The data take the same form as 
for the C_NEW command. A SIGWINCH signal is also sent 
to the process in the window, so that the process knows 
that the window has been reshaped and it can get the 
new window parameters. 

Disable network xt flow control [see xtproto(5)]. 
Enable network xt flow control [see xtproto(5)]. 
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NAME 

math - math functions and constants 

SYNOPSIS 

♦include <math.h> 

DESCRIPTION 

This file contains declarations of all the functions in the Math Library (described 
in Section 3M), as well as various functions in the C Library (Section 3C) that 
return floating-point values. 

It defines the structure and constants used by the matherrOM) error-handling 
mechanisms, including the following constant used as a error-return value: 

HUGE The maximum value of a single-precision floating-point number. 

The following mathematical constants are defined for user convenience: 

MJE The base of natural logarithms (e). 

M_L0G2E The base-2 logarithm of e. 

M_LOG10E The base-10 logarithm of e. 

M_LN2 The natural logarithm of 2. 

M_LN10 The natural logarithm of 10. 

MJPI K, the ratio of the circumference of a circle to its diameter. 

M_PI_2 71/2. 
M_PI_4 7C/4. 

M_1_PI 1/71. 

M_2__PI 2/71. 
M_2_SQRTPI 2/V7C. 

M__SQRT2 The positive square root of 2. 

M__SQRT1_2 The positive square root of 1 /2. 

The following mathematical constants are also defined in this header file: 

MAXFLOAT The maximum value of a non-infinite single-precision floating 
point number. 

HUGE__VAL positive infinity. 

For the definitions of various machine-dependent constants, see values(5). 

SEE ALSO 

intro(3), inatherr(3M), values(5). 
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NAME 

prof - profile within a function 

SYNOPSIS 

#de£ine MARK 
♦include <prof .h> 

void MARK (name) ; 

DESCRIPTION 

MARK introduces a mark called name that is treated the same as a function entry 
point. Execution of the mark adds to a counter for that mark, and program- 
counter time spent is accounted to the immediately preceding mark or to the 
function if there are no preceding marks within the active function. 

name may be any combination of letters, numbers, or underscores. Each name in 
a single compilation must be unique, but may be the same as any ordinary pro- 
gram symbol. 

For marks to be effective, the symbol MARK must be defined before the header file 
prof .h is included, either by a preprocessor directive as in the synopsis, or by a 
command line argument: 

cc -p -DMARK foo.c 

If MARK is not defined, the MARK (nam^) statements may be left in the source files 
containing them and are ignored, prof -g must be used to get information on 
all labels. 



In this example, marks can be used to determine how much time is spent in each 
loop. Unless this example is compiled with MARK defined on the command line, 
the marks are ignored. 

♦include <prof .h> 

foo( ) 

{ 



EXAMPLE 



int i, j; 



MARK(loopl) 
for (i = 0; 



i < 2000; i++) { 



} 

MARK(loop2) 
for (j - 0; 



j < 2000; { 



} 



SEE ALSO 



prof(l), prof il(2), roonitor(3C). 
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NAME 

regexp: compile, step, advance - regular expression compile and match rou- 
tines 

SYNOPSIS 

tdefine INIT declarations 
#def ine GETC (void) geic code 
♦define PEEKC (void) peekc code 
♦define UNGETC (void) ungetc code 
♦define RETURN (ptr) return code 
♦define ERROR (ua/) error code 

♦include <rege3qp.h> 

char *CQropile (char *instring, char *e3qpbuf , char *endbuf , int eof ) ; 
int step (char *string, char *expbuf ) ; 
int advance (char *string, char *e3qpbuf ) ; 
extern char *locl, *loc2, *locs; 
DESCRIPTION 

These functions are general purpose regular expression matching routines to be 
used in programs that perform regular expression matching. These functions are 
defined by the <rege3qp.h> header file. 

The functions step and advance do pattern matching given a character string 
and a compiled regular expression as input. 

The function conpile takes as input a regular expression as defined below and 
produces a compiled expression that can be used with step or advance. 

A regular expression specifies a set of character strings. A member of this set of 
strings is said to be matched by the regular expression. Some characters have 
special meaning when used in a regular expression; other characters stand for 
themselves. 

The regular expressions available for use with the regexp functions are con- 
structed as follows: 

Expression Meaning 

c the character c where c is not a special character. 

\c the character c where c is any character, except a digit in the range 

1-9. 

the beginning of the line being compared. 

$ the end of the line being compared. 

any character in the input. 

[s] any character in the set s, where s is a sequence of characters and /or 

a range of characters, e.g., [c-c] . 
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any character not in the set s, where s is defined as above, 

zero or more successive occurrences of the regular expression r. The 
longest leftmost match is chosen. 

the occurrence of regular expression r followed by the occurrence of 
regular expression jc. (Concatenation) 

any niimber of m through n successive occurrences of the regular 
expression r. The regular expression r\{m\} matches exactly m 
occurrences; r\{m,\) matches at least m occurrences. 

the regular expression r. When \n (where n is a number greater 
than zero) appears in a constructed regular expression, it stands for 
the regular expression x where x is the n regular expression 
enclosed in \( and \) that appeared earlier in the constructed regu- 
lar expression. For example, \ (r\) x\ (y\)z\2 is the concatenation of 
regular expressions rxyzy. 

Characters that have special meaning except when they appear within square 
brackets ([ ]) or are preceded by \ are: *, [, \. Other special characters, such 
as $ have special meaning in more restricted contexts. 

The character ^ at the beginning of an expression permits a successful match only 
immediately after a newline, and the character $ at the end of an expression 
requires a trailing newline. 

Two characters have special meaning only when used within square brackets. 
The character - denotes a range, [c-c], unless it is just after the open bracket or 
before the closing bracket, [-c] or [c-j in which case it has no special meaning. 
When used within brackets, the character has the meaning complement of if it 
immediately follows the open bracket (example: [ "^c] ); elsewhere between brack- 
ets (example: [c^]) it stands for the ordinary character ^, 

The special meaning of the \ operator can be escaped only by preceding it with 
another \, e.g. \\. 

Programs must have the following five macros declared before the #include 
<rege:q>.h> statement. These macros are used by the coitpile routine. The 
macros GETC, PEEKC, and UNGETC operate on the regular expression given as 
input to compile. 

GETC This macro returns the value of the next character (byte) in the 

regular expression pattern. Successive calls to GETC should 
return successive characters of the regular expression. 

PEEKC This macro returns the next character (byte) in the regular 

expression. Immediately successive calls to PEEKC should return 
the same character, which should also be the next character 
returned by GETC. 

UNGETC This macro causes the argument c to be returned by the next call 

to GETC and PEEKC. No more than one character of pushback is 
ever needed and this character is guaranteed to be the last char^ 
acter read by GETC. The return vidue of the macro UNGETC (c) is 
always ignored. 



r* 

rx 

r\{m,n\} 
\(A) 
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RETURN iptr) This macro is used on normal exit of the conpile routine. The 
value of the argument ptr is a pointer to the character after the 
last character of the compiled regular expression. This is useful 
to programs which have memory allocation to manage. 

ERROR (i?a/) This macro is the abnormal return from the conpile routine. 

The argument ml is an error number [see ERRORS below for 
meanings]. This call should never return. 

The syntax of the conpile routine is as follows: 

conpile {instring, expbuf, endbuf, eof) 

The first parameter, instring, is never used explicitly by the conpile routine but 
is useful for programs that pass down different pointers to input characters. It is 
sometimes used in the INIT declaration (see below). Programs which call func- 
tions to input characters or have characters in an external array can pass down a 
value of (char *) 0 for this parameter. 

The next parameter, expbuf, is a character pointer. It points to the place where 
the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where the compiled 
regular expression may be placed. If the compiled expression cannot fit in 
(endbuf-e:q?buf ) bytes, a call to ERROR (50) is made. 

The parameter eof is the character which marks the end of the regular expression. 
This character is usually a /. 

Each program that includes the <regexp.h> header file must have a #define 
statement for INIT. It is used for dependent declarations and initializations. 
Most often it is used to set a register variable to point to the beginning of the reg- 
ular expression so that this register variable can be used in the declarations for 
GETC, PEEKC, and UNGETC. Otherwise it can be used to declare external variables 
that might be used by (31TC, PEEKC and UNGETC. [See EXAMPLE below.] 

The first parameter to the step and advance functions is a pointer to a string of 
characters to be checked for a match. This string should be null terminated. 

The second parameter, expbuf, is the compiled regular expression which was 
obtained by a call to the ftmction conpile. 

The function step returns non-zero if some substring of string matches the regu- 
lar expression in expbuf and zero if there is no match. If there is a match, two 
external character pointers are set as a side effect to the call to step. The variable 
loci points to the first character that matched the regular expression; the variable 
loc2 points to the character after the last character that matches the regular 
expression. Thus if the regular expression matches the entire input string, loci 
will point to the first character of string and loc2 will point to the null at the end 
of string. 

The function advance returns non-zero if the initial substring of string matches 
the regular expression in expbuf. If there is a match, an external character pointer, 
loc2, is set as a side effect. The variable loc2 points to the next character in 
string after the last character that matched. 
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When advance encounters a * or \{ \} sequence in the regular expression, it 
will advance its pointer to the string to be matched as far as possible and will 
recursively call itself trying to match the rest of the string to the rest of the regu- 
lar expression. As long as there is no match, advance will back up along the 
string until it finds a match or reaches the point in the string that initially 
matched the * or \ { \ } . It is sometimes desirable to stop this backing up before 
the initial point in the string is reached. If the external character pointer Iocs is 
equal to the point in the string at sometime during the backing up process, 
advance will break out of the loop that backs up and will return zero. 

The external variables circf, sed, and nbra are reserved. 

DIAGNOSTICS 

The function coirpile uses the macro RETURN on success and the macro ERROR on 
failure (see above). The functions step and advance return non-zero on a suc- 
cessful match and zero if there is no match. Errors are: 



11 


range endpoint too large. 


16 


bad number. 


25 


\ digit out of range. 


36 


illegal or missing delimiter. 


41 


no remembered search string. 


42 


\( \) imbalance. 


43 


too many \(. 


44 


more than 2 numbers given in \ { \ } . 


45 


} expected after \. 


46 


first number exceeds second in \ { \ } 


49 


[ ] imbalance. 


50 


regular expression overflow. 


EXAMPLE 





The following is an example of how the regular expression macros and calls 
might be defined by an application program: 

♦define INIT register char *sp « instring; 

♦define GETC (*sp++) 

♦define PEEKC (*sp) 

♦define UNGETC(c) (~sp) 

♦define RETURN (*c) return; 

♦define ERROR (c) regerr 

♦include <regexp.h> 

(void) conpile (*argv, expbuf , fiexpbuf [ESIZE] , ' \0' ) / 

if (stepdinebuf r e^buf)) 
succeed; 
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NAME 

Stat - data returned by stat system call 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/stat.h> 

DESCRIPTION 

The system calls stat and f stat return data in a stat structure, which is 
defined in stat . h. 

The constants used in the st_mode field are also defined in this file: 

/* type of file */ 
/* access mode bits */ 
/* fifo */ 

/* character special */ 
/* directory */ 

/* XENIX special named file */ 
/* XENIX semaphore subtype of IFNAM */ 
/♦ XENIX shared data subtype of IFNAM */ 
/* block special */ 
/* regular */ 
/* symbolic link */ 
/* set user id on execution */ 
/* set group id on execution ♦/ 
/* save swapped text even after use */ 
/♦ read permission, owner */ 
/* write permission, owner */ 
/* execute/search permission, owner ♦/ 
/* record locking enforcement flag */ 
/* read, write, execute: owner */ 
/* read permission: owner */ 
/* write permission: owner */ 
/* execute permission: owner */ 
/* read, write, execute: group */ 
/* read permission: group */ 
/* write permission: group */ 
/* execute permission: group */ 
/* read, write, execute: other */ 
/* read permission: other */ 
/* write permission: other */ 
/* execute permission: other ♦/ 



♦define 


S 


IFMT 


♦define 


s" 


"iamb 


♦define 


s" 


"iFIFO 


♦define 


s' 


'iFCHR 


♦define 




JFDIR 


♦define 




'iFNAM 


♦define 


s" 


'iNSEM 


♦define 


s" 


"iNSHD 


♦define 


s' 


"iFBLK 


♦define 




"iFREG 


♦define 


s" 


'iFLNK 


♦define 


s' 


JSUID 


♦define 




JSGID 


♦define 


s" 


"iSVTX 


♦define 


s" 


JREAD 


♦define 


s" 


IWRITE 


♦define 


s' 


JEXEC 


♦define 


s" 


ENFbfT 


♦define 


s" 


'iRWXU 


♦define 


s" 


'iRUSR 


♦define 


s" 


"iWUSR 


♦define 


s' 


"iXUSR 


♦define 


s" 


"iRWXG 


♦define 


s" 


"iRGRP 


♦define 


s" 


"iWGRP 


♦define 


s" 


'iXGRP 


♦define 


s" 


"iRWXD 


♦define 


s" 


"iROTH 


♦define 


s" 


"iWOTH 


♦define 


s" 


'iXOTH 
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The following macros are for POSIX eonformance: 



tdefine 
tdefine 
#de£ine 
tdefine 
tdefine 

SEE ALSO 

stat(2), types(5). 



S__ISBLK(node) 
S_ISCHR(rocxie) 
S__ISDIR(mode) 
S_ISFIFO(mcxle) 
S ISREGdnode) 



block special file 
character special file 
directory file 
pipe or fifo file 
regular file 
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NAME 

stdarg - handle variable argtiment list 

SYNOPSIS 

♦include <stdarg.h> 

va_list pvar; 

void va_start (va_list pvar, panvN) ; 
type va_arg(va_list pvar, type); 
void vajend(va_list pvar); 
DESCRIPTION 

This set of macros allows portable procedures that accept variable numbers of 
arguments of variable types to be written. Routines that have variable argument 
lists [such as printf ] but do not use stdarg are inherently non-portable, as dif- 
ferent machines use different argument-passing conventions. 

va__list is a type defined for the variable used to traverse the list. 

The va_start() macro is invoked before any access to the unnamed arguments 
and initializes pvar for subsequent use by va__arg() and vajend(). The parame- 
ter parmN is the identifier of the rightmost parameter in the variable parameter 
list in the fimction definition (the one just before the , . . .). If this parameter is 
declared with the register storage class or with a function or array type, or 
with a type that is not compatible with the type that results after application of 
the default argument promotions, the behavior is undefined. 

The parameter parmN is required under strict ANSI C compilation. In other com- 
pilation modes, parmN need not be supplied and the second parameter to the 
va_start 0 macro can be left empty [e.g., va_start (pvar, ) ; ]. This allows for 
routines that contain no parameters before the ... in the variable parameter list. 

The va_arg ( ) macro expands to an expression that has the type and value of the 
next argument in the call. The parameter pvar should have been previously ini- 
tialized by va__start(). Each invocation of va_arg() modifies pvar so that the 
values of successive arguments are returned in turn. The parameter type is the 
type name of the next argument to be returned. The type name must be specified 
in such a way so that the type of a pointer to an object that has the specified type 
can be obtained simply by postfixing a * to type. If there is no actual next argu- 
ment, or if type is not compatible with the type of the actual next argument (as 
promoted according to the default argument promotions), the behavior is 
undefined. 

The vajendO macro is used to clean up. 

Multiple traversals, each bracketed by va_start and vajend, are possible. 
EXAMPLE 

This example gathers into an array a list of arguments that are pointers to strings 
(but not more than MAXARGS arguments) with function f 1, then passes the array 
as a single argument to function f2. The number of pointers is specified by the 
first argument to f 1. 
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♦include <stdarg.h> 
tdefine MAXARGS 31 

void fl(int njptrs, ...) 
{ 

va_list ap; 

char *array [MAXARGS] ; 

int ptr_no = 0; 

if (n_j>trs > MAXARGS) 

n__ptrs = MAXARGS; 
va_start (ap, n_ptrs) ; 
while (ptr_no < n_ptrs) 

array [ptr_no-H-] = va_arg(ap^ char*); 
va_end (ap) ; 
f2(nj>trs, array); 

} 

Each call to f 1 shall have visible the definition of the function or a declaration 
such as 

void fl(int, . . .) 

SEE ALSO 

vprintfOS). 

NOTES 

It is up to the calling routine to specify in some manner how many arguments 
there are, since it is not always possible to determine the number of arguments 
from the stack frame. For example, execl is passed a zero pointer to signal the 
end of the list, printf can tell how many arguments there are by the format. It 
is non-portable to specify a second argument of char, short, or float to 
va_arg, because arguments seen by the called function are not char, short, or 
float. C converts char and short arguments to int and converts float argu- 
ments to doiable before passing them to a function. 
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NAME 

types - primitive system data types 

SYNOPSIS 

tinclude <sys/types.h> 

DESCRIPTION 

The data types defined in types. h are used in UNIX System code. Some data of 
these types are accessible to user code: 



typedef 


struct { int r[l]; } *physa 


typedef 


long 


docket; 


typedef 


long 


daddr__t; 


typedef 


char ♦ 


caddr_t; 


typedef 


unsigned char 


unchar; 


typedef 


unsigned short 


ushort; 


typedef 


unsigned int 


uint; 


typedef 


unsigned long 


ulong; 


typedef 


ushort 


inojt; 


typedef 


ushort 


uidjt; 


typedef 


ushort 


gid_t; 


typedef 


ushort 


nlink__t; 


typedef 


ulong 


modest; 


typedef 


short 


cntjt; 


typedef 


long 


tixne t; 


typedef 


int 


label_t[6]; 


typedef 


short 


dev t; 


typedef 


long 


offjt; 


typedef 


long 


pid_t; 


typedef 


unsigned long 


paddr_t; 


typedef 


int 


key_t; 


typedef 


unsigned char 


use_t; 


typedef 


short 


sysid__t; 


typedef 


short 


index__t; 


typedef 


short 


lock_t; 


typedef 


unsigned int 


size_t; 


typedef 


long 


docket; 



The form daddr_t is used for disk addresses except in an i-node on disk, see 
fs(4). Times are encoded in seconds since 00:00:00 UTC, January 1, 1970. The 
major and minor parts of a device code specify kind and unit number of a device 
and are installation-dependent. Offsets are measured in bytes from the beginning 
of a file. The label_t variables are used to save the processor state while 
another process is running. 
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NAME 

values - machine-dependent values 

SYNOPSIS 

♦include <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined for particular 
processor architectures. 

The model assumed for integers is binary representation (one's or two's comple- 
ment), where the sign is represented by the value of the high-order bit. 

BITS (type) The number of bits in a specified type (e.g., int). 

HIBITS The value of a short integer with only the high-order bit set. 

HIBITL The value of a long integer with only the high-order bit set. 

HIBITI The value of a regular integer with only the high-order bit set. 

MAXSHORT The maximum value of a signed short integer. 

MAXLONG The maximum value of a signed long integer. 

MAXINT The maximum value of a signed regular integer. 

MAXFLOAT, LN_MAXFLOAT 

The maximum value of a single-precision floating-point number, 
and its natural logarithm. 

MAXDOUBLE, LNJ1AXD0UBLE 

The maximum value of a double-precision floating-point number, 
and its natural logarithm. 

MINFLOAT, LN JilNFIiOAT 

The minimum positive value of a single-precision floating-point 
number, and its natural logarithm. 

MINDOUBLE, LN JdlNDOUBLE 

The minimum positive value of a double-precision floating-point 
number, and its natural logarithm. 

FSIGNIF The number of significant bits in the mantissa of a single-precision 
floating-point number. 

DSIGNIF The number of significant bits in the mantissa of a double- 
precision floating-point ntimber. 

SEE ALSO 

intro(3), inath(5). 
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NAME 

varargs - handle variable argument list 

SYNOPSIS 

♦include <varargs.h> 

va_alist 
vajdcl 

va__list pvar; 

void va_start (va_list pvar) ; 
type va_arg(va_list pvar, type); 
void va_end(va__list pvar); 
DESCRIPTION 

This set of macros allows portable procedures that accept variable argument lists 
to be written. Routines that have variable argument lists [such as printf (3S)] 
but do not use varargs are inherently non-portable, as different machines use 
different argim\ent-passing conventions. 

va_alist is used as the parameter list in a function header. 

va_dcl is a declaration for va_jalist. No semicolon should follow va_dcl. 

va_list is a type defined for the variable used to traverse the list. 

va__start is called to initialize pvar to the beginning of the list. 

va_arg will return the next argtiment in the list pointed to by pvar. type is the 
type the argument is expected to be. Different types can be mixed, but it is up to 
the routine to know what type of argument is expected, as it cannot be deter- 
mined at runtime. 

va_jend is used to clean up. 

Multiple traversals, each bracketed by va_start and vajend^ are possible. 
EXAMPLE 

This example is a possible implementation of execl [see exec(2)]. 

♦include <unistd.h> 
♦include <varargs.h> 
♦define MAXARGS 100 

/* execl is called by 

execl (file, argl, arg2, (char *)0); 

*/ 

execl (va_alist) 

vajdcl 

{ 

va_list ap; 
char ffile; 

char *args [MAXARGS] ; /* assumed big enough*/ 

int argno = 0; 
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va_start (ap) ; 

file « va_jarg(apf char *); 

while ( (args [argno++] = va_arg(apr char *)) != 0) 
va_end(ap) ; 

return execv( file, args); 

} 

SEE ALSO 

exec(2), printf (3S), vprintf (3S), stciarg(5). 

NOTES 

It is up to the calling routine to specify in some manner how many arguments 
there are, since it is not always possible to determine the number of arguments 
from the stack frame. For example, execl is passed a zero pointer to signal the 
end of the list, printf can tell how many arguments are there by the format. 

It is non-portable to specify a second argtiment of char, short:, or float to 
va__arg, since argimients seen by the called ftmction are not char, short, or 
float. C converts char and short arguments to int and converts float argu- 
ments to double before passing them to a function. 

stdarg is the preferred interface. 
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NAME 

xtproto - multiplexed channels protocol used by xt driver 
DESCRIPTION 

This xt protocol is used for communication between multiple UNIX System host 
processes and an AT&T windowing terminal operating under the layers com- 
mand; see xt(7). It is a multiplexed protocol thai directs traffic between host 
processes and terminal windows, thereby allowing multiple virtual terminal ses- 
sions over a single connection. The protocol is implemented by the xt host driver 
and corresponding firmware in a windowing terminal. 

The xt driver implements two distinct low level protocols. Which protocol is 
used depends on the media used for communication with the terminal. The regu- 
lar xt protocol is used when communicating over unreliable media such as RS- 
232. The regular xt protocol provides flow control and error correction, thereby 
guaranteeing error-free delivery of data. The network xt protocol is used when 
commimicating over reliable media such as a local area network. In order to 
achieve maximum possible throughput, the network xt protocol relies on the 
underlying network to provide flow control and error correction. 

The layers command queries the windowing terminal whether to use regular or 
network xt protocol through an A__XTPROTO JAGENT ioctl system call [see 
layers(5)]. The layers command then decides what protocol to use based on 
the return value of A_XTPROTO, baud rate, and the -m option of layers. 

The regular xt protocol uses packets with a 2-byte header containing a 3-bit 
sequence ntimber, 3-bit channel number, control flag, and one byte for data size. 
The data part of packets sent from the host to the terminal may not be larger 
than 252 bytes. The maximum data part size can be less than 252 at lower baud 
rates, or if the -m option of layers was specified. Also, when communicating 
with some earlier windowing terminals, maximum data part size is fixed at 32 
bytes. The maximum data part size of packets sent from the terminal to the host 
is always fixed at 32 bytes. The trailer contains a CRC-16 code in 2 bytes. Each 
channel is double-buffered. 

Correctly received regular xt packets in sequence are acknowledged with a con- 
trol packet containing an ACK; however, out of sequence packets generate a con- 
trol packet containing a NAK, which causes the retransmission in sequence of all 
unacknowledged packets. 

Unacknowledged regular xt packets are retransmitted after a timeout interval 
that is dependent on baud rate. Another timeout parameter specifies the interval 
after which incomplete receive packets are discarded. 

Network xt protocol uses a 3-byte header containing a 3-bit channel number, 
various control flags, and 2-bytes for data size. The data part of packets sent from 
the host to the terminal has no size limit. The data part of packets sent from the 
terminal to the host is restricted to 1025 bytes. 

Since network xt protocol relies on the underlying media to guarantee error-free 
delivery of data, no CRC codes or timeouts are needed. 
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Network xt protocol provides a simple flow control mechanism to limit the 
amount of data sent to a window in the terminal before a NETWORK XT ACK ack- 
nowledgement is received by the host. The intent of this flow control is to limit 
the amount of data sent to a window in the terminal not reading its input 
because, for example, the user has pressed the scroll lock key. This is necessary to 
prevent data from backing up and blocking other data directed to other windows. 
To improve overall throughput, network xt flow control can be disabled by 
processes in the terminal that always read their input quickly. 

FILES 

/usr/ include/ sys/xtproto.h channel multiplexing protocol definitions 

SEE ALSO 

j agent (5), layer s(5). 

layers(l) in the User's Reference Manual. 

xt(7) in the Programmer's Guide: STREAMS, 



Page 2 



10/89 



